Skip to navigation
REST APIReference dataInstruments

Get an instrument

One instrument by id. One that another environment serves is 404. A removed instrument is still served, with its last status: the catalog keeps no tombstone, so its record stops changing. To look up by symbol, use GET /instruments?symbol=.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

instrumentIdstringRequired
The instrument id.

Headers

X-Request-IdstringOptional

Your own id for the request: 8 to 128 of [A-Za-z0-9._-]. It becomes the request’s id and is echoed on the response. A value off that grammar is replaced with a fresh id, never refused.

Response

The instrument.
instrumentIdstring
The instrument's id. Ids are opaque strings.
symbolstring

The canonical symbol, VENUE@BASE/QUOTE[:SETTLE[-DDMmmYY[-STRIKE-C|P]]]: OKX@BTC/USDT (spot), OKX@BTC/USDT:USDT (linear perpetual), BYBIT@BTC/USDT:USDT-25Jun27 (dated future), BYBIT@BTC/USDC:USDC-26Sep26-100000-C (call option). Byte-identical to the symbol on the market-data stream.

venueIdstring
The venue's id.
venuestring

The venue’s code, the display alias of venueId.

venueSymbolstring
The venue's own symbol for the instrument, as its API spells it.
typestring

The product shape: SPOT, FUTURES, INVERSE_FUTURES, QUANTO_FUTURES, PERPETUAL_SWAP, INVERSE_PERPETUAL_SWAP, QUANTO_PERPETUAL_SWAP, OPTION, INVERSE_OPTION or INDEX. Append-only: tolerate values you don’t know.

statusstring

The lifecycle status: LISTED (announced, not trading yet), OPEN (trading), SUSPENDED (trading halted), SETTLED (a dated product past settlement) or DELISTED (withdrawn). A halted market reads LISTED until the feed carries SUSPENDED. Append-only: tolerate values you don’t know.

baseAssetIdstring
The base asset's id.
baseAssetstring

The base asset’s symbol, the display alias of baseAssetId.

quoteAssetIdstring
The quote asset's id.
quoteAssetstring

The quote asset’s symbol, the display alias of quoteAssetId.

settleAssetIdstring or null

The id of the asset a derivative settles in. Null today for every row: the catalog does not state it, and the symbol’s :SETTLE token names the settlement asset.

settleAssetstring or null

The settlement asset’s symbol, the display alias of settleAssetId. Null whenever settleAssetId is.

feeAssetIdstring or null
The id of the asset trading fees are charged in. Null when unknown.
feeAssetstring or null

The symbol of the asset trading fees are charged in, the display alias of feeAssetId. Null whenever feeAssetId is.

contractMultiplierstring

The contract multiplier: the base-asset quantity one unit of the instrument represents. "1" for spot.

contractValuestring or null
One contract's notional in the quote asset, for inverse futures and inverse perpetual swaps. Null for every other shape, and null where the catalog states none.
tickSizestring

The price increment: every valid price is a multiple of it.

stepSizestring

The quantity increment: every valid quantity is a multiple of it.

priceMinstring or null
The lowest price the venue accepts. Null when the venue states none.
priceMaxstring or null
The highest price the venue accepts. Null when the venue states none.
qtyMinstring or null
The smallest order quantity. Null when the venue states none.
qtyMaxstring or null
The largest order quantity. Null when the venue states none.
minNotionalstring or null
The smallest order notional, in the quote asset. Null when the venue states none.
priceDecimalsinteger

The decimal places needed to render every valid price, derived from tickSize.

qtyDecimalsinteger

The decimal places needed to render every valid quantity, derived from stepSize.

makerFeeRatestring

The maker fee rate as a fraction of the notional: "0.001" is 10 basis points. "0" when the venue charges none; a rebate is negative.

takerFeeRatestring

The taker fee rate as a fraction of the notional. "0" when the venue charges none; a rebate is negative.

underlyingInstrumentIdstring or null

The id of the instrument a derivative is written on. Null today for every row: the catalog does not state it.

listedAtNsstring or nullformat: "^[0-9]+$"

When the catalog first knew the instrument (its createdAt), in epoch nanoseconds. Null when unknown.

expiresAtNsstring or nullformat: "^[0-9]+$"
When a dated future or option stops trading, in epoch nanoseconds. Null for a product without an expiry.
settlesAtNsstring or nullformat: "^[0-9]+$"
When a dated future or option settles, in epoch nanoseconds. Null for a product without a settlement.
updatedAtNsstring or nullformat: "^[0-9]+$"
When the instrument record last changed, as a sequencer timestamp in epoch nanoseconds. Statistics do not move it. Null when unknown.
tickerobject or null

An instrument’s latest trade and rolling-window statistics, at display precision; the market-data stream carries the exact values. Null unless include=ticker, and null for an instrument that has never traded or whose last price the projection cannot state. A window that is still warming is null, never 0.

Errors

400
Get Instruments Request Bad Request Error
401
Get Instruments Request Unauthorized Error
404
Get Instruments Request Not Found Error
503
Get Instruments Request Service Unavailable Error