{ "openapi": "3.1.0", "info": { "title": "Market Metrics", "version": "1.9.1", "description": "tastytrade Market Metrics API.", "contact": { "name": "tastytrade API support", "email": "api.support@tastytrade.com", "url": "https://developer.tastytrade.com" } }, "paths": { "/market-metrics": { "get": { "description": "Returns volatility and liquidity metrics for one or more underlyings in a single read-only request. Pass a comma-separated `symbols` query list (e.g. `?symbols=AAPL,FB,BRK%2FB`); each underlying is returned as a `MarketMetricInfo` object including IV index, IV rank/percentile, liquidity ratings, and per-expiration option implied volatilities. This is a snapshot endpoint.", "parameters": [ { "in": "query", "name": "symbols", "description": "Comma separated list of symbols i.e. ?symbols=AAPL,FB,BRK%2FB", "required": true, "schema": { "type": "string" }, "example": "AAPL,FB,BRK/B" } ], "responses": { "200": { "description": "An array of volatility and liquidity metrics, one entry per requested symbol.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MarketMetricInfo" } } }, "required": [ "items" ] }, "context": { "type": "string", "example": "/market-metrics" }, "pagination": { "type": "object", "description": "Paging metadata, present on paginated list responses.", "properties": { "per-page": { "type": "integer" }, "page-offset": { "type": "integer" }, "item-offset": { "type": "integer" }, "total-items": { "type": "integer" }, "total-pages": { "type": "integer" }, "current-item-count": { "type": "integer" } } } }, "required": [ "data", "context" ] } } } }, "401": { "description": "Missing or invalid `Authorization` bearer token (tokens expire after 15 minutes), or a missing/malformed `User-Agent` header. Send `Authorization: Bearer ` and a `User-Agent` like `my-app/1.0`.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "No valid access token was provided; access tokens expire after 15 minutes." } } } } } }, "403": { "description": "Authenticated, but not authorized to access this resource.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ], "example": { "error": { "code": "not_permitted", "message": "User not permitted access" } } } } } }, "422": { "description": "Unprocessable content — the request was invalid for this endpoint; the reason is returned in `error.message`.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ], "example": { "error": { "code": "preflight_check_failure", "message": "One or more preflight checks failed", "errors": [ { "code": "preflight_check_failure", "message": "A specific validation failed for this order." } ] } } } } } }, "429": { "description": "Request rate exceeded reasonable thresholds. Back off exponentially and retry.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ] } } } } }, "operationId": "getMarketMetricsIndex", "tags": [ "market-metrics" ], "x-tt-class": "read", "x-money-moving": false, "x-idempotent": true, "x-rate-limit-bucket": "read", "summary": "Get Market Metrics By Symbols" } }, "/market-metrics/historic-corporate-events/dividends/{symbol}": { "get": { "description": "Returns the historical dividend schedule for a single underlying identified by the `symbol` path parameter. Each entry reports the date the dividend occurred and the per-share amount, useful for reconciling payouts or estimating yield.", "parameters": [ { "in": "path", "name": "symbol", "description": "Symbol to get dividends data for", "required": true, "schema": { "type": "string" }, "example": "AAPL" } ], "responses": { "200": { "description": "An array of historical dividend records for the requested symbol.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DividendInfo" } } }, "required": [ "items" ] }, "context": { "type": "string", "example": "/market-metrics/historic-corporate-events/dividends/{symbol}" }, "pagination": { "type": "object", "description": "Paging metadata, present on paginated list responses.", "properties": { "per-page": { "type": "integer" }, "page-offset": { "type": "integer" }, "item-offset": { "type": "integer" }, "total-items": { "type": "integer" }, "total-pages": { "type": "integer" }, "current-item-count": { "type": "integer" } } } }, "required": [ "data", "context" ] } } } }, "401": { "description": "Missing or invalid `Authorization` bearer token (tokens expire after 15 minutes), or a missing/malformed `User-Agent` header. Send `Authorization: Bearer ` and a `User-Agent` like `my-app/1.0`.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "No valid access token was provided; access tokens expire after 15 minutes." } } } } } }, "403": { "description": "Authenticated, but not authorized to access this resource.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ], "example": { "error": { "code": "not_permitted", "message": "User not permitted access" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate exceeded reasonable thresholds. Back off exponentially and retry.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ] } } } } }, "operationId": "getMarketMetricsDividendsSymbol", "tags": [ "market-metrics" ], "x-tt-class": "read", "x-money-moving": false, "x-idempotent": true, "x-rate-limit-bucket": "read", "summary": "Get Historical Dividends" } }, "/market-metrics/historic-corporate-events/earnings-reports/{symbol}": { "get": { "description": "Returns historical earnings announcements for a single underlying identified by the `symbol` path parameter. Use the required `start-date` query parameter to bound the window from that date until now, and the optional `end-date` to cap the upper bound. Each entry reports the announcement date and reported earnings per share.", "parameters": [ { "in": "path", "name": "symbol", "description": "Symbol to get earnings data for", "required": true, "schema": { "type": "string" }, "example": "AAPL" }, { "in": "query", "name": "start-date", "description": "Limits earnings data from start-date until now", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2024-01-15" }, { "in": "query", "name": "end-date", "description": "Limits earnings data from start-date until end-date", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2024-01-15" } ], "responses": { "200": { "description": "An array of historical earnings records for the requested symbol within the requested date window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EarningsInfo" } } }, "required": [ "items" ] }, "context": { "type": "string", "example": "/market-metrics/historic-corporate-events/earnings-reports/{symbol}" }, "pagination": { "type": "object", "description": "Paging metadata, present on paginated list responses.", "properties": { "per-page": { "type": "integer" }, "page-offset": { "type": "integer" }, "item-offset": { "type": "integer" }, "total-items": { "type": "integer" }, "total-pages": { "type": "integer" }, "current-item-count": { "type": "integer" } } } }, "required": [ "data", "context" ] } } } }, "401": { "description": "Missing or invalid `Authorization` bearer token (tokens expire after 15 minutes), or a missing/malformed `User-Agent` header. Send `Authorization: Bearer ` and a `User-Agent` like `my-app/1.0`.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "No valid access token was provided; access tokens expire after 15 minutes." } } } } } }, "403": { "description": "Authenticated, but not authorized to access this resource.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ], "example": { "error": { "code": "not_permitted", "message": "User not permitted access" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ] } } } }, "422": { "description": "Unprocessable content — the request was invalid for this endpoint. Dates must be ISO-8601 (`YYYY-MM-DD`); the reason is returned in `error.message`.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ], "example": { "error": { "code": "preflight_check_failure", "message": "One or more preflight checks failed", "errors": [ { "code": "preflight_check_failure", "message": "A specific validation failed for this order." } ] } } } } } }, "429": { "description": "Request rate exceeded reasonable thresholds. Back off exponentially and retry.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard tastytrade error envelope. Branch on error.code, not the message text.", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code (see the Error reference)." }, "message": { "type": "string", "description": "Human-readable explanation." }, "errors": { "type": "array", "description": "Present for multi-error / validation failures; one entry per problem.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "domain": { "type": "string" } } } } } } }, "required": [ "error" ] } } } } }, "operationId": "getMarketMetricsEarningsSymbol", "tags": [ "market-metrics" ], "x-tt-class": "read", "x-money-moving": false, "x-idempotent": true, "x-rate-limit-bucket": "read", "summary": "Get Historical Earnings Reports" } } }, "servers": [ { "url": "https://api.cert.tastyworks.com", "description": "Sandbox" }, { "url": "https://api.tastyworks.com", "description": "Production" } ], "components": { "schemas": { "DividendInfo": { "type": "object", "properties": { "occurred-date": { "description": "The date the dividend occurred, in ISO-8601 (`YYYY-MM-DD`) format.", "type": "string", "format": "date", "example": "2025-02-10" }, "amount": { "description": "The dividend amount paid per share. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "0.25" } }, "description": "A single historical dividend record for an underlying — the date the dividend occurred and the per-share amount. Returned as an array by `GET /market-metrics/historic-corporate-events/dividends/{symbol}`." }, "EarningsInfo": { "type": "object", "properties": { "occurred-date": { "description": "The date of the earnings announcement, in ISO-8601 (`YYYY-MM-DD`) format.", "type": "string", "format": "date", "example": "2025-01-30" }, "eps": { "description": "The reported earnings per share for the announcement. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "2.40" } }, "description": "A single historical earnings record for an underlying — the announcement date and reported earnings per share. Returned as an array by `GET /market-metrics/historic-corporate-events/earnings-reports/{symbol}`." }, "MarketMetricInfo": { "type": "object", "properties": { "symbol": { "description": "The underlying symbol these metrics describe, in tastytrade symbology.", "type": "string", "example": "AAPL" }, "implied-volatility-index": { "description": "The implied-volatility index of the underlying. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "0.3125" }, "implied-volatility-index-5-day-change": { "description": "The 5-day change of the underlying's implied-volatility index. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "-0.0182" }, "implied-volatility-rank": { "description": "The implied-volatility rank of the underlying. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "0.4567" }, "implied-volatility-percentile": { "description": "The implied-volatility percentile of the underlying. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "0.5210" }, "liquidity": { "description": "A measure of the underlying's liquidity. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "12345.67" }, "liquidity-rank": { "description": "The liquidity rank of the underlying. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "0.8123" }, "liquidity-rating": { "description": "The liquidity rating of the underlying. Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal", "example": "4" }, "option-expiration-implied-volatilities": { "description": "Per-expiration implied-volatility data for the underlying's option chain, one entry per expiration date.", "type": "array", "items": { "type": "object", "properties": { "expiration-date": { "description": "Option expiration date", "type": "string", "format": "date-time" }, "settlement-type": { "description": "AM or PM settlement", "type": "string" }, "option-chain-type": { "description": "Option chain type i.e. Standard or Non-standard.", "type": "string" }, "implied-volatility": { "description": "Implied volatility of option expiration Decimal value serialized as a JSON string (e.g. \"150.25\").", "type": "string", "format": "decimal" } } } } }, "description": "Volatility and liquidity metrics for a single underlying, including the underlying's implied-volatility index, IV rank/percentile, liquidity ratings, and a list of per-expiration option implied volatilities. Returned by `GET /market-metrics`." } } }, "x-tastytrade-service": { "serviceName": "market-metrics-server", "group": "market-metrics", "title": "Market Metrics" }, "tags": [ { "name": "market-metrics" } ] }