Symbol Formats: Stocks, Options, FX, Crypto and Futures
Details
Docs navigation
- Getting started: Quickstart, Authentication, Rate limits, Errors and retries
- Guides: Symbol formats (you are here), Timestamps and time zones, Pagination, Split and dividend adjustments, WebSocket streaming, Dataset downloads, Excel and Google Sheets, Changelog
- API reference: Stock bars, Stock trades and quotes, Snapshots and movers, Tickers, exchanges, calendar, Splits and dividends, Fundamentals and SEC filings, Options chain and Greeks, Options EOD, bars, OI, Forex, Crypto, Crypto derivatives, Futures bars and continuous, Settlements and COT, Indices, Economic data, Technical indicators
- SDKs: Python, JavaScript
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
figiorcikfrom 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_changewithold_symbolandnew_symbol. - Crypto pairs are exchange-specific.
BTC-USDTonbinanceand on another exchange are different markets; passexchangeto choose one. BTC-USDwithout an exchange means our cross-venue aggregate.- FX pairs follow market convention. We return
EURUSD, notUSDEUR; ask for the inverse and you getinvalid_symbol_formatwith 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.