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.

Response

The instrument.
baseAssetstring

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

baseAssetIdstring
The base asset's id.
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.
expiresAtNsstring or nullformat: "^[0-9]+$"
When a dated future or option stops trading, in epoch nanoseconds. Null for a product without an expiry.
feeAssetstring or null

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

feeAssetIdstring or null
The id of the asset trading fees are charged in. Null when unknown.
instrumentIdstring
The instrument's id. Ids are opaque strings.
listedAtNsstring or nullformat: "^[0-9]+$"

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

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.

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.

priceMaxstring or null
The highest price the venue accepts. Null when the venue states none.
priceMinstring or null
The lowest price the venue accepts. Null when the venue states none.
qtyDecimalsinteger

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

qtyMaxstring or null
The largest order quantity. Null when the venue states none.
qtyMinstring or null
The smallest order quantity. Null when the venue states none.
quoteAssetstring

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

quoteAssetIdstring
The quote asset's id.
settleAssetstring or null

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

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.

settlesAtNsstring or nullformat: "^[0-9]+$"
When a dated future or option settles, in epoch nanoseconds. Null for a product without a settlement.
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.

stepSizestring

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

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.

takerFeeRatestring

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

tickSizestring

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

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. A window that is still warming is null, never 0.

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.

underlyingInstrumentIdstring or null

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

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.
venuestring

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

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

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