Early access is open. Free sample datasets are live now. Download a sample

Symbol Formats: Stocks, Options, FX, Crypto and Futures

Details

Docs navigation

One string identifies every instrument in the marketdata.co API, and each asset class has its own pattern. This page lists them all, explains the OCC option symbol format character by character, and shows how futures month codes work. Read it if you get invalid_symbol_format or symbol_not_found, or before you map symbols from another vendor.

Early access. These formats are the proposed v1 standard and are used in all our docs and sample files.

Details

Formats at a glance

Asset class Format Examples
US stocks and ETFs Exchange ticker, share class after a dot AAPL, SPY, BRK.B
Options on stocks and indices OCC symbol without padding AAPL261218C00200000, SPXW261218P06500000
Forex Base and quote ISO codes, no separator EURUSD, USDJPY
Crypto spot Base, hyphen, quote BTC-USD, BTC-USDT, ETH-USDT
Crypto perpetuals Pair plus -PERP BTC-USDT-PERP
Futures contract Root, month code, last digit of year ESZ6, CLF7
Continuous futures Root, .C, position ES.C1, ES.C2
Options on futures Contract, hyphen, type and strike ESZ6-C6000
Indices Plain index code SPX, NDX, DJI, RUT
Economic series Source series ID CPIAUCSL, DGS10

Symbols are upper case. Lower case input is accepted and converted.

Keep reading

Reading an OCC option symbol

The OCC option symbol format packs four facts into one string. Take AAPL261218C00200000:

Part Characters Meaning
Root AAPL Option root, usually the underlying ticker
Expiry 261218 YYMMDD, so 18 December 2026
Type C C for call, P for put
Strike 00200000 Strike times 1,000, padded to 8 digits, so 200.000

Parse it from the right, because roots vary in length:

Example (Python):

def parse_occ(sym: str) -> dict:
    root, rest = sym[:-15], sym[-15:]
    return {
        "root_symbol": root,
        "expiration_date": f"20{rest[0:2]}-{rest[2:4]}-{rest[4:6]}",
        "option_type": "call" if rest[6] == "C" else "put",
        "strike_price": int(rest[7:]) / 1000,
    }

print(parse_occ("SPXW261218P06500000"))
#> {'root_symbol': 'SPXW', 'expiration_date': '2026-12-18', 'option_type': 'put', 'strike_price': 6500.0}

OCC's official 21-character form pads the root with spaces to six characters (AAPL 261218C00200000). We drop the spaces. If you paste a padded symbol we strip them for you.

The root is not always the underlying. SPX weeklies use SPXW, and contracts adjusted after a split or merger can get a new root such as XYZ1. Every option record has both root_symbol and underlying_symbol so you never have to guess.

Code

Futures month codes

Month Code Month Code
January F July N
February G August Q
March H September U
April J October V
May K November X
June M December Z

ESZ6 is the December 2026 E-mini S&P 500. Because the single year digit repeats every ten years, ESZ6 could also mean 2016. The API always resolves it to the nearest listed contract, and the futures contract list carries an unambiguous contract_month (2026-12). For expired contracts older than ten years, use the contract_month filter rather than the short symbol.

Details

Mapping from other vendors

You have Send us
BRK-B, BRK/B, BRKB BRK.B
EUR/USD, EUR_USD, C:EURUSD EURUSD
BTCUSDT, X:BTCUSD BTC-USDT, BTC-USD
O:AAPL261218C00200000 AAPL261218C00200000
/ESZ26, ESZ2026 ESZ6
^GSPC, $SPX, I:SPX SPX

Watch out

Notes and gotchas

  • Tickers get reused. A symbol that belonged to a delisted company can be issued to a new one. Use figi or cik from the reference endpoint as a permanent key.
  • When a company changes ticker, history stays under the new symbol, and the corporate actions endpoint records the symbol_change with old_symbol and new_symbol.
  • Crypto pairs are exchange-specific. BTC-USDT on binance and on another exchange are different markets; pass exchange to choose one.
  • BTC-USD without an exchange means our cross-venue aggregate.
  • FX pairs follow market convention. We return EURUSD, not USDEUR; ask for the inverse and you get invalid_symbol_format with a hint.

Keep reading

Next steps

Details

Was this page useful?

[Yes] [No]

Missing a symbol or a venue? Tell us on the custom data form.