# Instruments Metadata API {% hint style="info" %} Instruments metadata API is available only for active [pro and business](https://docs.tardis.dev/faq/billing-and-subscriptions#what-are-the-differences-between-subscription-types) subscriptions. {% endhint %} ## Authorization Please provide 'Authorization' header with value: 'Bearer YOUR\_API\_KEY'. ## Single instrument info endpoint Returns instrument info for provided exchange and symbol. ### endpoint URL format ### example URLs * * ### response format {% hint style="info" %} `changes` info returned by the API is meant to be accurate and complete only for contractMultiplier values (we monitor exchanges announcements for that), rest of the changes are done on best effort basis and not always complete. {% endhint %} ```typescript { id: string // symbol id datasetId?: string // id used for CSV datasets downloads, may differ from id exchange: string // exchange id baseCurrency: string // normalized, so for example bitmex XBTUSD has base currency set to BTC not XBT quoteCurrency: string // normalized, so for example bitfinex BTCUST has quote currency set to USDT, not UST type: 'spot' | 'perpetual' | 'future' | 'option' | 'combo' contractType?: "move" | "linear_future" | "inverse_future" | "quanto_future" | "linear_perpetual" | "inverse_perpetual" | "quanto_perpetual" | "put_option" | "call_option" | "turbo_put_option" | "turbo_call_option" | "spread" | "interest_rate_swap" | "repo" | "index" // only for derivatives, detailed contract type active: boolean // indicates if the instrument can currently be traded availableSince: string // Tardis data collection start date in ISO format, may differ from exchange listing date availableTo?: string // date in ISO format listing?: string // exchange listing date in ISO format, if known expiry?: string // in ISO format, only for futures and options expirationType?: 'daily' | 'weekly' | 'next_week' | 'quarter' | 'next_quarter' // expiration schedule type underlyingIndex?: string // the underlying index for derivatives underlyingType?: UnderlyingType // underlying asset class; omitted for options priceIncrement: number // price tick size, price precision can be calculated from it amountIncrement: number // amount tick size, amount/size precision can be calculated from it minTradeAmount: number // min order size minNotional?: number // minimum order notional value, when separately exposed by the exchange makerFee: number // consider it as illustrative only, as it depends in practice on account traded volume levels, different categories, VIP levels, owning exchange currency etc takerFee: number // consider it as illustrative only, as it depends in practice on account traded volume levels, different categories, VIP levels, owning exchange currency etc inverse?: boolean // only for derivatives contractMultiplier?: number // only for derivatives quanto?: boolean // set to true for quanto instruments, otherwise undefined settlementCurrency?: string // settlement currency, only for quanto instruments as it has different base/quote currency strikePrice?: number // strike price, only for options optionType?: 'call' | 'put' // option type, only for options marginMode?: 'isolated' | 'cross' // margin mode margin?: boolean // whether margin trading is supported (spot) aliasFor?: string // if this instrument is an alias for another changes?: { until: string // date in ISO format priceIncrement?: number amountIncrement?: number contractMultiplier?: number minTradeAmount?: number minNotional?: number makerFee?: number takerFee?: number quanto?: boolean inverse?: boolean settlementCurrency?: string underlyingIndex?: string contractType?: ContractType quoteCurrency?: string type?: string }[] } // where ContractType is one of: type ContractType = | "move" | "linear_future" | "inverse_future" | "quanto_future" | "linear_perpetual" | "inverse_perpetual" | "quanto_perpetual" | "put_option" | "call_option" | "turbo_put_option" | "turbo_call_option" | "spread" | "interest_rate_swap" | "repo" | "index" // where UnderlyingType is one of: type UnderlyingType = | "native" | "equity" | "commodity" | "fixed_income" | "fx" | "index" | "pre_market" ``` {% hint style="info" %} `underlyingType` is returned for active/current non-option instruments. Crypto-native instruments default to `native`; exchange-sourced non-native classifications such as `equity`, `commodity`, `fx`, `index`, `fixed_income`, and `pre_market` are returned when available. Older historical or delisted instruments may not have `underlyingType`. Options omit `underlyingType` to keep large options metadata responses compact. `minNotional` is returned only when the exchange exposes a minimum order value or notional separately from minimum order quantity. {% endhint %} {% hint style="info" %} **`changes` field semantics:** * The `changes` array is sorted chronologically by `until` (ascending). Each entry records field values that were valid **before** the `until` date — i.e., the values changed at `until`. * Only `contractMultiplier` changes are guaranteed to be accurate and complete (monitored from exchange announcements). Other field changes (`priceIncrement`, `amountIncrement`) are tracked on a best-effort basis. * Changes are filtered to the instrument's `availableSince`—`availableTo` range. {% endhint %} {% hint style="info" %} **Lifecycle field semantics:** * `active` — reflects whether the instrument can currently be traded on the exchange. Use this to filter for live instruments. * `availableTo` — set when Tardis stops collecting data for an instrument (e.g., after expiry or delisting). This field is updated after the fact and may lag behind the actual exchange delisting. * Some exchanges reuse symbol IDs or maintain alias/legacy symbols alongside active ones. Both may appear in metadata results — use `active` to distinguish currently tradable instruments. {% endhint %} ### sample response ```javascript { "id": "XBTUSD", "datasetId": "XBTUSD", "exchange": "bitmex", "baseCurrency": "BTC", "quoteCurrency": "USD", "type": "perpetual", "active": true, "availableSince": "2019-03-30T00:00:00.000Z", "priceIncrement": 0.5, "amountIncrement": 1, "minTradeAmount": 1, "makerFee": -0.00025, "takerFee": 0.00075, "inverse": true, "contractType": "inverse_perpetual", "contractMultiplier": 1 } ``` ## Instruments filter endpoint Returns instruments array for given exchange matching provided optional filter ### endpoint URL [https://api.tardis.dev/v1/instruments/:exchange?filter={filter\_payload}](https://api.tardis.dev/v1/instruments/:exchange?filter=%7Bfilter_payload%7D) ### example URLs * * [https://api.tardis.dev/v1/instruments/okex-futures?filter={"baseCurrency":"BTC","active":true}](https://api.tardis.dev/v1/instruments/okex-futures?filter=%7B%22baseCurrency%22:%22BTC%22,%22active%22:true%7D) * [https://api.tardis.dev/v1/instruments/bitmex?filter={"baseCurrency":"BTC","quoteCurrency":\["USD","USDT"\],"type":"perpetual"}](https://api.tardis.dev/v1/instruments/bitmex?filter=%7B%22baseCurrency%22:%22BTC%22,%22quoteCurrency%22:%5B%22USD%22,%22USDT%22%5D,%22type%22:%22perpetual%22%7D) * [https://api.tardis.dev/v1/instruments/binance-futures?filter={"underlyingType":"commodity","type":"perpetual","active":true}](https://api.tardis.dev/v1/instruments/binance-futures?filter=%7B%22underlyingType%22:%22commodity%22,%22type%22:%22perpetual%22,%22active%22:true%7D) ### optional filter object format JSON object, when provided via query string it needs to be URL encoded. ```typescript { baseCurrency: string | string[] | undefined quoteCurrency: string | string[] | undefined type: string | string[] | undefined contractType: string | string[] | undefined underlyingType: UnderlyingType | UnderlyingType[] | undefined active: boolean | undefined availableSince: string | undefined // ISO date string; returns instruments with availableSince on or before this date availableTo: string | undefined // ISO date string accepted by the API; not a general instrument.availableTo result filter } ``` {% hint style="info" %} `availableSince` filters results by collection start date. `availableTo` is accepted and validated by the API, but it is not a generic "ended before this date" predicate; use the returned `availableTo` field when you need to inspect an instrument's collection end date. {% endhint %} ### sample request in JavaScript ```javascript const payload = { baseCurrency: 'BTC', quoteCurrency: ['USD', 'USDT'], type: 'perpetual' } const headers = { Authorization: 'Bearer YOUR_API_KEY' } const encodedPayload = encodeURIComponent(JSON.stringify(payload)) await fetch(`https://api.tardis.dev/v1/instruments/bitmex?filter=${encodedPayload}`, { headers }) ``` ### response format Array of instruments objects as described for single instrument endpoint ## Client helpers for symbol discovery Client helpers find exchange-specific instrument symbol IDs from normalized market criteria, so you do not have to hardcode each exchange's symbol format. They use the Instruments Metadata API to return the correct `id` for each requested exchange, ready to pass to replay, streaming, or raw data feeds. Use the `datasetId` selector only when you need symbols for direct CSV dataset file downloads. Returned symbols are exchange-provided IDs and are not normalized by the clients. {% tabs %} {% tab title="Node.js" %} Find active BTC/USDT linear perpetuals across exchanges with different native symbol formats. ```javascript import { findInstrumentSymbols, init } from 'tardis-dev' init({ apiKey: 'YOUR_API_KEY' }) const symbolsByExchange = await findInstrumentSymbols(['bitmex', 'binance-futures', 'okex-swap', 'bybit'], { baseCurrency: 'BTC', quoteCurrency: 'USDT', contractType: 'linear_perpetual', active: true }) console.log(symbolsByExchange) // [ // { exchange: 'bitmex', symbols: ['XBTUSDT'] }, // { exchange: 'binance-futures', symbols: ['btcusdt'] }, // { exchange: 'okex-swap', symbols: ['BTC-USDT-SWAP'] }, // { exchange: 'bybit', symbols: ['BTCUSDT'] } // ] ``` Find active Tesla equity instruments by filtering on `underlyingType`. ```javascript const teslaEquitySymbols = await findInstrumentSymbols( ['binance-futures', 'okex-swap', 'coinbase-international', 'bybit', 'bitget-futures'], { baseCurrency: 'TSLA', underlyingType: 'equity', active: true } ) console.log(teslaEquitySymbols) // [ // { exchange: 'binance-futures', symbols: ['tslausdt'] }, // { exchange: 'okex-swap', symbols: ['TSLA-USDT-SWAP'] }, // { exchange: 'coinbase-international', symbols: ['TSLA-PERP'] }, // { exchange: 'bybit', symbols: ['TSLAUSDT'] }, // { exchange: 'bitget-futures', symbols: ['TSLAUSDT'] } // ] ``` ```javascript const csvSymbolsByExchange = await findInstrumentSymbols( ['bitmex', 'binance-futures', 'okex-swap', 'bybit'], { baseCurrency: 'BTC', quoteCurrency: 'USDT', contractType: 'linear_perpetual', active: true }, 'datasetId' ) ``` {% endtab %} {% tab title="Python" %} Find active BTC/USDT linear perpetuals across exchanges with different native symbol formats. ```python from tardis_dev import find_instrument_symbols symbols_by_exchange = find_instrument_symbols( ["bitmex", "binance-futures", "okex-swap", "bybit"], { "baseCurrency": "BTC", "quoteCurrency": "USDT", "contractType": "linear_perpetual", "active": True, }, api_key="YOUR_API_KEY", ) print(symbols_by_exchange) # [ # {"exchange": "bitmex", "symbols": ["XBTUSDT"]}, # {"exchange": "binance-futures", "symbols": ["btcusdt"]}, # {"exchange": "okex-swap", "symbols": ["BTC-USDT-SWAP"]}, # {"exchange": "bybit", "symbols": ["BTCUSDT"]}, # ] ``` Find active Tesla equity instruments by filtering on `underlyingType`. ```python tesla_equity_symbols = find_instrument_symbols( ["binance-futures", "okex-swap", "coinbase-international", "bybit", "bitget-futures"], { "baseCurrency": "TSLA", "underlyingType": "equity", "active": True, }, api_key="YOUR_API_KEY", ) print(tesla_equity_symbols) # [ # {"exchange": "binance-futures", "symbols": ["tslausdt"]}, # {"exchange": "okex-swap", "symbols": ["TSLA-USDT-SWAP"]}, # {"exchange": "coinbase-international", "symbols": ["TSLA-PERP"]}, # {"exchange": "bybit", "symbols": ["TSLAUSDT"]}, # {"exchange": "bitget-futures", "symbols": ["TSLAUSDT"]}, # ] ``` ```python from tardis_dev import find_instrument_symbols_async csv_symbols_by_exchange = await find_instrument_symbols_async( ["bitmex", "binance-futures", "okex-swap", "bybit"], { "baseCurrency": "BTC", "quoteCurrency": "USDT", "contractType": "linear_perpetual", "active": True, }, selector="datasetId", api_key="YOUR_API_KEY", ) ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tardis.dev/api/instruments-metadata-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.