Instruments and identifiers

Every instrument (a listing, an FX or crypto pair, a futures family or its continuous series, or a reference series) has one key, and every data route addresses it by that key. To find the key for a name or a code, see finding an instrument.

Instrument keys

Each key has a kind prefix. A route takes the key whole, or the key without its prefix.

kind	key grammar	examples	route
security	security:{SYMBOL} or security:{MIC}:{SYMBOL}	security:AAPL, security:XNAS:AAPL	/v1/securities/AAPL/quote
futures family	future:{MIC}:{ROOT}	future:XCME:ES, future:XNYM:CL	/v1/futures/XCME:ES
continuous futures	future:{MIC}:{ROOT}/continuous	future:XCME:ES/continuous	/v1/futures/XCME:ES/continuous/quote
FX pair	fx:{BASEQUOTE} (ISO 4217 codes)	fx:EURUSD, fx:USDJPY	/v1/fx/EURUSD/quote
crypto pair	crypto:{BASE-QUOTE} (as the exchange lists it)	crypto:BTC-USDT	/v1/crypto/pairs/BTC-USDT/quote
series	series:{series_key}	series:us.cpi.all_items.sa, series:us.equity_index.sp500	/v1/series/us.cpi.all_items.sa

Case

The kind prefix must be lowercase. Security:AAPL is refused 422 invalid_request.

The rest of the key is case-folded: a series key to lowercase, a ticker, an FX pair, a futures root and a crypto pair to uppercase (fx:eurusd reads as fx:EURUSD). Route segments fold the same way, and an answer always names the key in its canonical case.

FX direction

Each maintained pair is served in one direction only. The inverse spelling (fx:USDEUR) is 404 not_maintained, and the message names the maintained pair (USDEUR = 1 / EURUSD). A pair of circulating currencies outside the maintained pairs is also 404 not_maintained; any other code is 404 not_registered.

Security keys and venue forms

A listing's canonical key is security:{SYMBOL}, with the ticker it holds now, whenever that ticker names one current listing.

security:{MIC}:{SYMBOL} is an accepted input that names the listing's venue, answered with the canonical key: /v1/securities/XNAS:AAPL/quote answers instrument.key security:AAPL. In a batch, the quotes map stays keyed by the key you sent.

When a ticker names several current listings, the plain form is 409 ambiguous_instrument, and the message names the venue forms; each of those listings' canonical key is then its venue form. A venue form whose ticker is held by a listing on another venue is 404 not_registered, and the message names that listing's key. Which routes serve a venue form is on stocks and ETFs.

A ticker that no listing holds now, but that a listing held before, resolves to its most recent former holder, and identity.resolved_from names the ticker you asked for (null otherwise).

A delisted listing's key is its bare ticker only while no other listing, current or delisted, holds that ticker; otherwise it is its venue form (listing lifecycle).

Series keys

A series key reads {area}.{measure}[.{qualifier}…]: us.treasury.cmt_yield.10y, us.unemployment_rate.u3.sa.

An economic or physical series ends in .sa or .nsa exactly when its seasonal_adjustment says so; a series with no seasonal variant (not_applicable), a rate, a yield, a spread and an index level carry no qualifier. Units are in the series block (series values), not in the key.

Futures families and continuous series

future:XCME:ES is the E-mini S&P 500 contract family, which has no quote; its price series is future:XCME:ES/continuous. A bare root (/v1/futures/ES) resolves while exactly one registered family has that code (futures).

External codes

An external statistical or exchange code can be found by search but is not a key. As a key it is refused 422 invalid_request; as a route segment, 404 not_registered. Either message names the key to use.

Identifiers

Beside its key, an instrument carries identifiers in its identity (from GET /v1/instruments/{key}). Every field is described in the API reference.

• A security's figi and composite_figi are never the key. A null one says why in identity.field_states (reason codes).
• The lifecycle fields are on listing lifecycle.
• SEC answers name a registrant by its cik, which identifies an SEC registrant, not a listing (filings and financials).

Object kinds

classification.object_kind says what an instrument is:

object kind	what it is	examples
tradable	a listing, a spot pair	security:AAPL, fx:EURUSD, crypto:BTC-USDT
reference_series	a published measure, not traded: an index level, a rate, an economic statistic	series:us.cpi.all_items.sa
contract_family	a futures root: the family of its dated contracts, not itself priced	future:XCME:ES
derived_series	a family's continuous front-month series	future:XCME:ES/continuous

Asset class and instrument type

Every instrument's classification carries these facets; GET /v1/taxonomy gives each term's definition and the asset_subclass values of each asset class.

facet	meaning
asset_class	the economic exposure: equity, rates, credit, fx, commodity, crypto; or mixed, unknown, not_applicable (a statistic of the economy as a whole)
instrument_type	the wrapper. Traded: stock, etf, fund, bond, spot, future, option, perpetual. Reference: index, rate, economic, physical. Or unknown
underlying_asset_class	for a wrapper (an ETF, a fund, a future), the exposure it wraps; null otherwise
asset_subclass	an optional narrowing of asset_class; null when none is assigned
object_kind	object kinds

An equity sector is not a commodity subclass: security:XLE is equity / etf with a null subclass, while future:XNYM:CL is commodity / future with subclass energy. A company's GICS sector is read on the security (stocks and ETFs).