# tastytrade Open API Documentation > Agent-first docs for the tastytrade Open API. Every page is available as Markdown (append `.md` or send `Accept: text/markdown`). ## Getting Started - [Home](http://localhost:3000/index.md): Landing page. ## Get started - [Quickstart](http://localhost:3000/docs/get-started.md): Zero to your first call: credentials, a 15-minute token, list accounts, and a safe sandbox order. - [Agent Quickstart](http://localhost:3000/docs/agent-quickstart.md): End-to-end agent walkthrough: discover, auth, quote, dry-run, order, confirm — safely. ## Authentication - [OAuth2 authentication](http://localhost:3000/docs/authentication/oauth2.md): Register an app, exchange a refresh token for a 15-minute access token, and send Bearer + User-Agent. ## Concepts - [Accounts & Customers](http://localhost:3000/docs/concepts/accounts-and-customers.md): The customer to accounts model, authority levels, and the me shortcut. - [Instruments & Symbology](http://localhost:3000/docs/concepts/instruments-and-symbology.md): Equities, options (OCC), futures, future options, and crypto symbology. - [Orders & Order Types](http://localhost:3000/docs/concepts/orders-and-order-types.md): Order/leg structure, order types, time-in-force, and complex orders (OTO/OCO/OTOCO). - [Order Lifecycle](http://localhost:3000/docs/concepts/order-lifecycle.md): Order status from submission through working to terminal, and partial fills. - [Positions & Balances](http://localhost:3000/docs/concepts/positions-and-balances.md): Balances (cash, net-liq, buying power) and positions (quantity, mark, cost basis). - [Market Data](http://localhost:3000/docs/concepts/market-data.md): REST market data by instrument type, fields, and the 100-symbol batch limit. - [Streaming](http://localhost:3000/docs/concepts/streaming.md): DXLink market-data streaming and the account-update WebSocket. - [Margin & Risk](http://localhost:3000/docs/concepts/margin-and-risk.md): Margin requirements, the margin dry-run, trading status, and risk parameters. ## Guides - [Idempotency & retries](http://localhost:3000/docs/guides/idempotency-and-retries.md): Safe retries with a unique external-identifier + status checks (no idempotency-key header; the API does not deduplicate). - [Rate limits & backoff](http://localhost:3000/docs/guides/rate-limits-and-backoff.md): 429 thresholds, failed-login IP block, exponential backoff, streaming/batching to reduce load. - [Place an equity order](http://localhost:3000/docs/guides/place-an-equity-order.md): Step-by-step: dry-run then submit a single-leg equity order, safely. - [Multi-leg spreads](http://localhost:3000/docs/guides/multi-leg-spreads.md): Build verticals, iron condors, and strangles as multi-leg option orders. - [Error handling](http://localhost:3000/docs/guides/error-handling.md): Read the error envelope, branch on the code, and recover via the doc_url anchor convention. - [Stream market data](http://localhost:3000/docs/guides/stream-market-data.md): Connect to the DXLink market-data WebSocket: token, SETUP/AUTH, channel, subscribe, read feed. - [Stream account updates](http://localhost:3000/docs/guides/stream-account-updates.md): Subscribe to the account WebSocket for live order, position, and balance notifications. - [Run a backtest](http://localhost:3000/docs/guides/backtesting.md): Submit a backtest, poll for completion, and read the results. - [Manage watchlists](http://localhost:3000/docs/guides/watchlists.md): Create, read, update, and delete watchlists and their entries. - [Pagination & filtering](http://localhost:3000/docs/guides/pagination-and-filtering.md): Page through large collections and filter/sort list endpoints. ## SDKs & Tools - [MCP Server](http://localhost:3000/docs/sdks-and-tools/mcp-server.md): tastytrade MCP server — Tools/Resources/Prompts + dry-run-first safety model (managed, not self-hosted). ## Help - [FAQ](http://localhost:3000/docs/faq.md): Common questions: unconfirmed_user, invalid_credentials, 401s, IP blocks, User-Agent, sandbox. ## API Reference - [Error reference](http://localhost:3000/reference/errors.md): HTTP + domain error codes with causes & fixes (machine list at http://localhost:3000/errors.json). ### Account Status - [GET /accounts/{account_number}/trading-status](http://localhost:3000/reference/account-status/getAccountsAccountNumberTradingStatus.md): Get Account Trading Status ### Accounts and Customers - [GET /api-quote-tokens](http://localhost:3000/reference/accounts-and-customers/getApiQuoteTokens.md): Get API Quote Token - [GET /customers/{customer_id}](http://localhost:3000/reference/accounts-and-customers/getCustomersCustomerId.md): Get Customer - [GET /customers/{customer_id}/accounts](http://localhost:3000/reference/accounts-and-customers/getCustomersCustomerIdAccounts.md): List Customer Accounts - [GET /customers/{customer_id}/accounts/{account_number}](http://localhost:3000/reference/accounts-and-customers/getCustomersCustomerIdAccountsAccountNumber.md): Get Account ### Backtesting - [GET /available-dates](http://localhost:3000/reference/backtesting/getAvailableDates.md): List Available Date Ranges - [GET /backtests](http://localhost:3000/reference/backtesting/getUsersBacktests.md): List Your Backtests - [POST /backtests](http://localhost:3000/reference/backtesting/postBacktests.md): Create A Backtest - [GET /backtests/{id}](http://localhost:3000/reference/backtesting/getBacktests.md): Get Backtest By ID - [POST /backtests/{id}/cancel](http://localhost:3000/reference/backtesting/cancelBacktests.md): Cancel A Running Backtest - [GET /backtests/{id}/logs](http://localhost:3000/reference/backtesting/getBacktestsLogs.md): Get Backtest Logs - [POST /simulate-trade](http://localhost:3000/reference/backtesting/simulateTrade.md): Simulate A Single Trade ### Balances and Positions - [GET /accounts/{account_number}/balance-snapshots](http://localhost:3000/reference/balances-and-positions/getAccountsAccountNumberBalanceSnapshots.md): List Account Balance Snapshots - [GET /accounts/{account_number}/balances](http://localhost:3000/reference/balances-and-positions/getAccountsAccountNumberBalances.md): Get Account Balances - [GET /accounts/{account_number}/balances/{currency}](http://localhost:3000/reference/balances-and-positions/getAccountsAccountNumberBalancesCurrency.md): Get Account Balance By Currency - [GET /accounts/{account_number}/positions](http://localhost:3000/reference/balances-and-positions/getAccountsAccountNumberPositions.md): List Account Positions ### Instruments - [GET /futures-option-chains/{symbol}](http://localhost:3000/reference/instruments/getFuturesOptionChainsSymbol.md): List Detailed Futures Option Chains - [GET /futures-option-chains/{symbol}/nested](http://localhost:3000/reference/instruments/getFuturesOptionChainsSymbolNested.md): List Nested Futures Option Chains - [GET /instruments/cryptocurrencies](http://localhost:3000/reference/instruments/getInstrumentsCryptocurrencies.md): List Cryptocurrencies - [GET /instruments/cryptocurrencies/{symbol}](http://localhost:3000/reference/instruments/getInstrumentsCryptocurrenciesSymbol.md): Get Cryptocurrency - [GET /instruments/equities](http://localhost:3000/reference/instruments/getInstrumentsEquities.md): List Equities - [GET /instruments/equities/{symbol}](http://localhost:3000/reference/instruments/getInstrumentsEquitiesSymbol.md): Get Equity - [GET /instruments/equities/active](http://localhost:3000/reference/instruments/getInstrumentsEquitiesActive.md): List Active Equities - [GET /instruments/equity-options](http://localhost:3000/reference/instruments/getInstrumentsEquityOptions.md): List Equity Options - [GET /instruments/equity-options/{symbol}](http://localhost:3000/reference/instruments/getInstrumentsEquityOptionsSymbol.md): Get Equity Option - [GET /instruments/future-option-products](http://localhost:3000/reference/instruments/getInstrumentsFutureOptionProducts.md): List Future Option Products - [GET /instruments/future-option-products/{exchange}/{root_symbol}](http://localhost:3000/reference/instruments/getInstrumentsFutureOptionProductsExchangeRootSymbol.md): Get Future Option Product - [GET /instruments/future-option-products/{root_symbol}](http://localhost:3000/reference/instruments/getInstrumentsFutureOptionProductsRootSymbol.md): Get Future Option Product By Root - [GET /instruments/future-options](http://localhost:3000/reference/instruments/getInstrumentsFutureOptions.md): List Future Options - [GET /instruments/future-options/{symbol}](http://localhost:3000/reference/instruments/getInstrumentsFutureOptionsSymbol.md): Get Future Option - [GET /instruments/future-products](http://localhost:3000/reference/instruments/getInstrumentsFutureProducts.md): List Future Products - [GET /instruments/future-products/{exchange}/{code}](http://localhost:3000/reference/instruments/getInstrumentsFutureProductsExchangeCode.md): Get Future Product - [GET /instruments/futures](http://localhost:3000/reference/instruments/getInstrumentsFutures.md): List Futures - [GET /instruments/futures/{symbol}](http://localhost:3000/reference/instruments/getInstrumentsFuturesSymbol.md): Get Future - [GET /instruments/quantity-decimal-precisions](http://localhost:3000/reference/instruments/getInstrumentsQuantityDecimalPrecisions.md): List Quantity Decimal Precisions - [GET /instruments/warrants](http://localhost:3000/reference/instruments/getInstrumentsWarrants.md): List Warrants - [GET /instruments/warrants/{symbol}](http://localhost:3000/reference/instruments/getInstrumentsWarrantsSymbol.md): Get Warrant - [GET /option-chains/{symbol}](http://localhost:3000/reference/instruments/getOptionChainsSymbol.md): List Detailed Option Chains - [GET /option-chains/{symbol}/compact](http://localhost:3000/reference/instruments/getOptionChainsSymbolCompact.md): List Compact Option Chains - [GET /option-chains/{symbol}/nested](http://localhost:3000/reference/instruments/getOptionChainsSymbolNested.md): List Nested Option Chains ### Margin Requirements - [POST /margin/accounts/{account_number}/dry-run](http://localhost:3000/reference/margin-requirements/createMarginAccountsAccountNumberDryRun.md): Margin Requirements Dry Run - [GET /margin/accounts/{account_number}/requirements](http://localhost:3000/reference/margin-requirements/getMarginAccountsAccountNumberRequirements.md): Get Account Margin Requirements ### Market Data - [GET /market-data/by-type](http://localhost:3000/reference/market-data/getMarketDataByType.md): Get Quotes By Instrument Type ### Market Metrics - [GET /market-metrics](http://localhost:3000/reference/market-metrics/getMarketMetricsIndex.md): Get Market Metrics By Symbols - [GET /market-metrics/historic-corporate-events/dividends/{symbol}](http://localhost:3000/reference/market-metrics/getMarketMetricsDividendsSymbol.md): Get Historical Dividends - [GET /market-metrics/historic-corporate-events/earnings-reports/{symbol}](http://localhost:3000/reference/market-metrics/getMarketMetricsEarningsSymbol.md): Get Historical Earnings Reports ### Market Sessions - [GET /market-time/equities/holidays](http://localhost:3000/reference/market-sessions/getMarketTimeEquitiesHolidays.md): Get Equity Market Holidays - [GET /market-time/equities/sessions/current](http://localhost:3000/reference/market-sessions/getMarketTimeEquitiesSessionsCurrent.md): Get Current Equities Session - [GET /market-time/equities/sessions/next](http://localhost:3000/reference/market-sessions/getMarketTimeEquitiesSessionsNext.md): Get Next Equities Session - [GET /market-time/equities/sessions/previous](http://localhost:3000/reference/market-sessions/getMarketTimeEquitiesSessionsPrevious.md): Get Previous Equities Session - [GET /market-time/futures/holidays/{instrument_collection}](http://localhost:3000/reference/market-sessions/getMarketTimeFuturesHolidaysInstrumentCollection.md): Get Futures Market Holidays By Exchange - [GET /market-time/futures/sessions/current](http://localhost:3000/reference/market-sessions/getMarketTimeFuturesSessionsCurrent.md): Get Current Futures Sessions - [GET /market-time/futures/sessions/current/{instrument_collection}](http://localhost:3000/reference/market-sessions/getMarketTimeFuturesSessionsCurrentInstrumentCollection.md): Get Current Futures Session By Exchange - [GET /market-time/futures/sessions/next/{instrument_collection}](http://localhost:3000/reference/market-sessions/getMarketTimeFuturesSessionsNextInstrumentCollection.md): Get Next Futures Session By Exchange - [GET /market-time/futures/sessions/previous/{instrument_collection}](http://localhost:3000/reference/market-sessions/getMarketTimeFuturesSessionsPreviousInstrumentCollection.md): Get Previous Futures Session By Exchange - [GET /market-time/sessions](http://localhost:3000/reference/market-sessions/getMarketTimeSessions.md): List Sessions For Date Range - [GET /market-time/sessions/current](http://localhost:3000/reference/market-sessions/getMarketTimeSessionsCurrent.md): Get Current Sessions By Collection ### Net Liquidating Value History - [GET /accounts/{accountNumber}/net-liq/history](http://localhost:3000/reference/net-liquidating-value-history/getNetLiqHistory.md): Get Net-Liq History For Account ### Orders - [GET /accounts/{account_number}/complex-orders](http://localhost:3000/reference/orders/getAccountsAccountNumberComplexOrders.md): List Complex Orders - [POST /accounts/{account_number}/complex-orders](http://localhost:3000/reference/orders/postAccountsAccountNumberComplexOrders.md): Submit Complex Order - [GET /accounts/{account_number}/complex-orders/{id}](http://localhost:3000/reference/orders/getAccountsAccountNumberComplexOrdersId.md): Get Complex Order - [DELETE /accounts/{account_number}/complex-orders/{id}](http://localhost:3000/reference/orders/deleteAccountsAccountNumberComplexOrdersId.md): Cancel Complex Order - [PATCH /accounts/{account_number}/complex-orders/{id}](http://localhost:3000/reference/orders/patchAccountsAccountNumberComplexOrdersId.md): Edit PAIRS Complex Order - [POST /accounts/{account_number}/complex-orders/{id}/dry-run](http://localhost:3000/reference/orders/postAccountsAccountNumberComplexOrdersIdDryRun.md): Dry Run Complex Order Edit - [POST /accounts/{account_number}/complex-orders/dry-run](http://localhost:3000/reference/orders/postAccountsAccountNumberComplexOrdersDryRun.md): Dry Run Complex Order - [GET /accounts/{account_number}/complex-orders/live](http://localhost:3000/reference/orders/getAccountsAccountNumberComplexOrdersLive.md): List Today's Complex Orders - [GET /accounts/{account_number}/orders](http://localhost:3000/reference/orders/getAccountsAccountNumberOrders.md): Search Orders - [POST /accounts/{account_number}/orders](http://localhost:3000/reference/orders/postAccountsAccountNumberOrders.md): Submit Order - [GET /accounts/{account_number}/orders/{id}](http://localhost:3000/reference/orders/getAccountsAccountNumberOrdersId.md): Get Order - [PUT /accounts/{account_number}/orders/{id}](http://localhost:3000/reference/orders/putAccountsAccountNumberOrdersId.md): Replace Order - [DELETE /accounts/{account_number}/orders/{id}](http://localhost:3000/reference/orders/deleteAccountsAccountNumberOrdersId.md): Cancel Order - [PATCH /accounts/{account_number}/orders/{id}](http://localhost:3000/reference/orders/patchAccountsAccountNumberOrdersId.md): Edit Order - [POST /accounts/{account_number}/orders/{id}/dry-run](http://localhost:3000/reference/orders/postAccountsAccountNumberOrdersIdDryRun.md): Dry Run Order Edit - [POST /accounts/{account_number}/orders/{id}/reconfirm](http://localhost:3000/reference/orders/postAccountsAccountNumberOrdersIdReconfirm.md): Reconfirm Order - [POST /accounts/{account_number}/orders/dry-run](http://localhost:3000/reference/orders/postAccountsAccountNumberOrdersDryRun.md): Dry Run Order - [GET /accounts/{account_number}/orders/live](http://localhost:3000/reference/orders/getAccountsAccountNumberOrdersLive.md): List Today's Orders - [GET /customers/{customer_id}/orders](http://localhost:3000/reference/orders/getCustomersCustomerIdOrders.md): Search Customer Orders - [GET /customers/{customer_id}/orders/live](http://localhost:3000/reference/orders/getCustomersCustomerIdOrdersLive.md): List Customer's Today's Orders ### Quote Alerts - [GET /quote-alerts](http://localhost:3000/reference/quote-alerts/getQuoteAlerts.md): List Quote Alerts - [POST /quote-alerts](http://localhost:3000/reference/quote-alerts/postQuoteAlerts.md): Create Quote Alert - [DELETE /quote-alerts/{alert_external_id}](http://localhost:3000/reference/quote-alerts/deleteQuoteAlertsAlertExternalId.md): Cancel Quote Alert ### Risk Parameters - [GET /accounts/{account_number}/margin-requirements/{underlying_symbol}/effective](http://localhost:3000/reference/risk-parameters/getAccountsAccountNumberMarginRequirementsUnderlyingSymbolEffective.md): Get Effective Margin Requirements - [GET /accounts/{account_number}/position-limit](http://localhost:3000/reference/risk-parameters/getAccountsAccountNumberPositionLimit.md): Get Account Position Limit - [GET /margin-requirements-public-configuration](http://localhost:3000/reference/risk-parameters/getMarginRequirementsPublicConfiguration.md): Get Public Margin Configuration - [GET /span/rows](http://localhost:3000/reference/risk-parameters/getSpanRows.md): Get SPAN File Rows ### Symbol Search - [GET /symbols/search/{symbol}](http://localhost:3000/reference/symbol-search/searchSymbols.md): Search Symbols ### Transactions - [GET /accounts/{account_number}/transactions](http://localhost:3000/reference/transactions/getAccountsAccountNumberTransactions.md): List Account Transactions - [GET /accounts/{account_number}/transactions/{id}](http://localhost:3000/reference/transactions/getAccountsAccountNumberTransactionsId.md): Get Transaction By ID - [GET /accounts/{account_number}/transactions/total-fees](http://localhost:3000/reference/transactions/getAccountsAccountNumberTransactionsTotalFees.md): Get Total Fees For A Day ### Watchlists - [GET /pairs-watchlists](http://localhost:3000/reference/watchlists/getPairsWatchlists.md): List Pairs Watchlists - [GET /pairs-watchlists/{pairs_watchlist_name}](http://localhost:3000/reference/watchlists/getPairsWatchlistsPairsWatchlistName.md): Get Pairs Watchlist - [GET /public-watchlists](http://localhost:3000/reference/watchlists/getPublicWatchlists.md): List Public Watchlists - [GET /public-watchlists/{watchlist_name}](http://localhost:3000/reference/watchlists/getPublicWatchlistsWatchlistName.md): Get Public Watchlist - [GET /watchlists](http://localhost:3000/reference/watchlists/getWatchlists.md): List Watchlists - [POST /watchlists](http://localhost:3000/reference/watchlists/postWatchlists.md): Create Watchlist - [GET /watchlists/{watchlist_name}](http://localhost:3000/reference/watchlists/getWatchlistsWatchlistName.md): Get Watchlist - [PUT /watchlists/{watchlist_name}](http://localhost:3000/reference/watchlists/putWatchlistsWatchlistName.md): Replace Watchlist - [DELETE /watchlists/{watchlist_name}](http://localhost:3000/reference/watchlists/deleteWatchlistsWatchlistName.md): Delete Watchlist ## Downloads - Postman collection: http://localhost:3000/postman/tastytrade.postman_collection.json (environment: http://localhost:3000/postman/tastytrade.postman_environment.json) - Streaming AsyncAPI 2.6: http://localhost:3000/asyncapi/tastytrade-streaming.asyncapi.json (http://localhost:3000/asyncapi/tastytrade-streaming.asyncapi.yaml) - Account Status OpenAPI 3.1: http://localhost:3000/openapi/account-status.json (http://localhost:3000/openapi/account-status.yaml) - Accounts and Customers OpenAPI 3.1: http://localhost:3000/openapi/accounts-and-customers.json (http://localhost:3000/openapi/accounts-and-customers.yaml) - Backtesting OpenAPI 3.1: http://localhost:3000/openapi/backtesting.json (http://localhost:3000/openapi/backtesting.yaml) - Balances and Positions OpenAPI 3.1: http://localhost:3000/openapi/balances-and-positions.json (http://localhost:3000/openapi/balances-and-positions.yaml) - Instruments OpenAPI 3.1: http://localhost:3000/openapi/instruments.json (http://localhost:3000/openapi/instruments.yaml) - Margin Requirements OpenAPI 3.1: http://localhost:3000/openapi/margin-requirements.json (http://localhost:3000/openapi/margin-requirements.yaml) - Market Data OpenAPI 3.1: http://localhost:3000/openapi/market-data.json (http://localhost:3000/openapi/market-data.yaml) - Market Metrics OpenAPI 3.1: http://localhost:3000/openapi/market-metrics.json (http://localhost:3000/openapi/market-metrics.yaml) - Market Sessions OpenAPI 3.1: http://localhost:3000/openapi/market-sessions.json (http://localhost:3000/openapi/market-sessions.yaml) - Net Liquidating Value History OpenAPI 3.1: http://localhost:3000/openapi/net-liquidating-value-history.json (http://localhost:3000/openapi/net-liquidating-value-history.yaml) - Orders OpenAPI 3.1: http://localhost:3000/openapi/orders.json (http://localhost:3000/openapi/orders.yaml) - Quote Alerts OpenAPI 3.1: http://localhost:3000/openapi/quote-alerts.json (http://localhost:3000/openapi/quote-alerts.yaml) - Risk Parameters OpenAPI 3.1: http://localhost:3000/openapi/risk-parameters.json (http://localhost:3000/openapi/risk-parameters.yaml) - Symbol Search OpenAPI 3.1: http://localhost:3000/openapi/symbol-search.json (http://localhost:3000/openapi/symbol-search.yaml) - Transactions OpenAPI 3.1: http://localhost:3000/openapi/transactions.json (http://localhost:3000/openapi/transactions.yaml) - Watchlists OpenAPI 3.1: http://localhost:3000/openapi/watchlists.json (http://localhost:3000/openapi/watchlists.yaml) ## Instructions Canonical golden-path guidance for agents using the tastytrade Open API. This is the single source for the `## Instructions` block in `/llms.txt`, the `/instructions.md` page, and `/skill.md` (G-7). Keep it accurate and short. ## Environments - **Sandbox** (default for development): `https://api.cert.tastyworks.com` — use this until verified. Data resets ~every 24h; quotes are delayed. - **Production**: `https://api.tastyworks.com` — real money. Only after explicit human approval. ## Authentication - Obtain an OAuth2 **access token** (15-minute expiry) and send it as `Authorization: Bearer ` on every request. - **Always set a `User-Agent` header** — requests without one are rejected. - Never log, echo, or commit tokens or secrets. ## Placing orders (money-moving — follow exactly) 1. **Dry-run first.** Submit the order to the dry-run / margin-dry-run endpoint and confirm it returns **no errors** (check buying-power and margin impact). 2. **Only then submit** — and set a unique **`external-identifier`** in the order body so you can recognize the order on retry (it is echoed back on the order object; responses also carry a system-assigned `ext-client-order-id`). tastytrade has **no idempotency-key header and does NOT deduplicate retried submissions**: if a submit is uncertain (timeout/5xx), query your live/recent orders for your `external-identifier` **before** resubmitting. See the idempotency & retries guide. 3. Prefer **sandbox** until the full flow is verified. Treat order placement as irreversible; get human confirmation for production. ## Symbology Use tastytrade symbology: equities (`AAPL`), OCC equity options, futures (prefixed `/`), future options (prefixed `./`), and cryptocurrency pairs. ## Market data & streaming - REST market data: `GET /market-data/by-type` (≤100 symbols). - Streaming: DXLink WebSocket with the **COMPACT** format; obtain an API quote token (`GET /api-quote-tokens`, 24h expiry) first. ## Rate limits & errors - Respect rate limits; on `429`, **back off exponentially** and retry. - Branch on the error **code**, not message text. Map API errors to the error reference for remediation. ## MCP server For agent-driven workflows, consider the tastytrade **MCP server** — self-hosted and open source at https://github.com/tastytrade/tastytrade-mcp. The five order-submitting tools are gated behind a dry-run-first confirmation token; the other seven destructive tools act on the first call. **Its default endpoint is production** — set `TASTYTRADE_ENV=sandbox`, or `TASTYTRADE_READ_ONLY=1` to withhold every write. See the MCP server docs.