Instruments Metadata API

Tick sizes, contract multipliers, base/quote currencies and expiration dates

Instruments metadata API is available only for active pro and business subscriptions.

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

https://api.tardis.dev/v1/instruments/:exchange/:symbol_id

example URLs

• https://api.tardis.dev/v1/instruments/bitmex/XBTUSD

• https://api.tardis.dev/v1/instruments/okex-swap/BTC-USDT-SWAP

response format

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.

{
	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
	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 notional value
	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
		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"

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.

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.

sample response

{
  "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}

example URLs

• https://api.tardis.dev/v1/instruments/bitmex

• https://api.tardis.dev/v1/instruments/okex-futures?filter={"baseCurrency":"BTC","active":true}

• https://api.tardis.dev/v1/instruments/bitmex?filter={"baseCurrency":"BTC","quoteCurrency":["USD","USDT"],"type":"perpetual"}

optional filter object format

JSON object, when provided via query string it needs to be URL encoded.

{
	baseCurrency: string | string[] | undefined
	quoteCurrency: string | string[] | undefined
	type: string | string[] | undefined
	contractType: string | string[] | undefined
	active: boolean | undefined
}

sample request in 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