tastytradeDeveloper Docs
Legacy ↗

Instruments & Symbology

An instrument is any single tradeable security at tastytrade: an equity, equity option, future, future option, or cryptocurrency. Every instrument has a unique symbol that is its primary identifier. You need that symbol to look up an instrument, to build order legs, and to read the positions an order creates. Getting symbology right is therefore the foundation of every trading workflow.

This page explains the symbol format for each instrument type and where those symbols show up. For the full request/response shapes, see /reference/instruments.

How symbols flow through the API

The same symbol string is reused across the platform:

  • Instrument lookup — fetch an instrument's full definition under /instruments/....
  • Order legs — each leg references a symbol plus an instrument type, quantity, and action.
  • Positions — when an order fills, the resulting position carries the same symbol.

Because symbols are passed verbatim, encoding matters. Symbols that contain a / (futures, future options, crypto) or whitespace (OCC options) must be URL-encoded when placed in a path or query string. For example /ESU3 becomes %2FESU3, and BTC/USD becomes BTC%2FUSD. JSON bodies use the raw, unencoded symbol.

A few platform conventions apply to every instrument request. Send a User-Agent header in product/version form (for example my-client/1.0) or the request is rejected, set Content-Type and Accept to application/json, and authenticate with a short-lived OAuth access token (Authorization: Bearer ...). Access tokens are minted by POST /oauth/token and expire after 15 minutes. JSON keys are dasherized, e.g. instrument-type and streamer-symbol. See Get started for the full setup.

Equities

Equity symbols are alphanumeric (A-Z, 0-9), occasionally containing a /:

AAPL
BRK/A

Each equity also exposes a streamer-symbol used by the market-data streamer, plus flags like is-index, is-etf, and is-fractional-quantity-eligible.

Equity options (OCC)

tastytrade uses the standard OCC format. A symbol is a fixed-width concatenation of four parts:

  1. Root — up to 6 alphanumeric characters, right-padded with spaces.
  2. Expiration — 6 digits, yymmdd.
  3. Type — C (call) or P (put).
  4. Strike — 8 digits, front-padded with zeros, strike multiplied by 1000 (no decimal point).
AAPL  220617P00150000   (AAPL Jun 17 2022 150 Put)
SPY   221118C00400000   (SPY  Nov 18 2022 400 Call)
SPXW  220520C04025000   (SPXW May 20 2022 4025 Call)

The strike rule: a 64.0 strike is 00064000, a 1050.55 strike is 01050550, a 0.50 strike is 00000500. Note the padding spaces between root and expiration are significant.

Futures (prefixed /)

Futures symbols start with a / followed by a contract code: product code (A-Z), a one-letter month code, and a 1-2 digit year.

/ESZ2   (E-mini S&P 500, December 2022)
/CLZ2   (Crude Oil, December 2022)
/VXX22  (CBOE Volatility Index, November 2022)

Product codes come from the future-products listing under /instruments. Remember to encode the leading / as %2F in URLs.

Future options (prefixed ./)

Each future option expiration series has its own product code, so a future option symbol carries both the future contract code and the option product code. The format is ./ + future contract code + option contract code + expiration + type (C/P) + strike:

./CLZ2 LO1X2 221104C91     (Nov 4 2022 91 Call settling into Dec CL)
./ESZ2 E1AZ2 221205P3720   (Dec 5 2022 3720 Put settling into Dec ES)

In ./ESZ2 E1AZ2 221205P3720, E1A is a weekly-Monday option product, ESZ2 is the underlying December ES contract. Encode the ./ prefix (and embedded spaces) for URLs, e.g. .%2FESZ2%20E1AZ2%20221205P3720.

Cryptocurrencies

Crypto symbols are a pair joined by /:

BTC/USD   (Bitcoin)
BCH/USD   (Bitcoin Cash)

The authoritative list is returned by GET /instruments/cryptocurrencies. Crypto is commonly traded in fractional quantities; the allowed precision is given per symbol (for example BTC/USD permits 8 decimal places). Encode the / as %2F in URLs.

Using symbols in orders

When you place an order, each leg references one of these symbols. Always submit a dry-run first to validate buying power and pricing before sending the live order. Order submission is not idempotent and there is no idempotency-key header — the API does not deduplicate retried submissions. Include a unique external-identifier in the order body so you can correlate it later; if a submission's outcome is uncertain (timeout or 5xx), check GET /accounts/{account_number}/orders for that identifier before resubmitting. See Idempotency & retries and Rate limits & backoff.

Errors

Lookups return standard codes: 400 (malformed request), 401 (missing/expired token), 404 (unknown symbol or endpoint), 422 (invalid filter combination — e.g. filtering future options by expiration-date alone, without the other required filters), 429 (rate limited), and 5xx (server error). See Errors for the full platform-wide set.

Related