> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.immix.xyz/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.immix.xyz/_mcp/server. # Search and list instruments GET /instruments The instruments this environment serves, searched and filtered, sorted by symbol unless `sort` says otherwise. `search` matches word prefixes of the symbol; `symbol` looks up exact symbols, at most 100 per call. Page with `limit` and `cursor`; `include` adds the exact `total`, the `facets` behind the filter panels, or each row's `ticker`. Reference: https://docs.immix.xyz/api-reference/rest-api/instruments/list ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Query parameters - `search` (string, optional) — Case-insensitive word prefixes, matched against the symbol's tokens, the venue's own symbol, the type and the id: `btc usdt` matches `OKX@BTC/USDT:USDT`, `perp` matches every perpetual swap. - `symbol` (string, optional) — Only these symbols, case-insensitive, at most 100; repeat the parameter or comma-separate. A symbol that does not exist is simply absent from the page. - `venueId` (string, optional) — Only these venue ids; repeat the parameter or comma-separate. - `venueId.notIn` (string, optional) — Every venue except these ids. - `venue` (string, optional) — Only these venues, by code (`okx`, `binance_usd-m`), case-insensitive. A code no venue has matches nothing. - `type` (string, optional) — Only these types: `SPOT`, `FUTURES`, `INVERSE_FUTURES`, `QUANTO_FUTURES`, `PERPETUAL_SWAP`, `INVERSE_PERPETUAL_SWAP`, `QUANTO_PERPETUAL_SWAP`, `OPTION`, `INVERSE_OPTION`, `INDEX`, or another type an instrument has. Any other value is 400. - `status` (string, optional) — Only these statuses: `LISTED`, `OPEN`, `SUSPENDED`, `SETTLED`, `DELISTED`, or another status an instrument has; any other value is 400. No default: send `status=OPEN` for the markets trading now. - `baseAssetId` (string, optional) — Only these base asset ids. - `baseAsset` (string, optional) — Only these base assets, by symbol (`BTC`), case-insensitive. A symbol no asset has matches nothing. - `quoteAssetId` (string, optional) — Only these quote asset ids. - `quoteAsset` (string, optional) — Only these quote assets, by symbol (`USDT`), case-insensitive. A symbol no asset has matches nothing. - `sort` (string, optional) — Comma-separated `symbol`, `instrumentId`, `type`, `listedAtNs`, `expiresAtNs`, `lastPx`, `pctChange24h`, `volume24h` or `turnover24h`; prefix `-` for descending. Default `symbol`. Absent values sort last in both directions: a time a row does not state, the statistics of an instrument that has never traded, a 24-hour statistic whose window is still warming, and any statistic the projection cannot state, such as a turnover it has no price to value. - `limit` (integer, optional) — Page size, 1-100; larger values are clamped. Default 50. - `cursor` (string, optional) — `nextCursor` or `prevCursor` from a previous page, sent with the same filters and sort. - `include` (string, optional) — `total` adds the exact count; `facets` adds counts per venue, type, base and quote asset; `ticker` adds each row's latest statistics. ## Response ### 200 A page of instruments. - `asOfSeqTsNs` (string, required, nullable) — The sequencer timestamp (epoch-ns) the data is complete through; also sent as X-Immix-As-Of-Seq-Ts. Null when unknown. - `facets` (Facets, required, nullable) — Counts of matching instruments per dimension, null unless `include=facets`. Each dimension is counted under the request's filters minus that dimension's own filter, so a filter panel keeps showing the alternatives to the choice made in it. Each `value` is what the matching filter takes: `venues` feeds `venueId`, `types` feeds `type`, `baseAssets` feeds `baseAssetId` and `quoteAssets` feeds `quoteAssetId`. Values with no matches are omitted; counts sort descending. - `items` (list of Instrument, required) - `nextCursor` (string, required, nullable) — Pass as `cursor` for the next page. Null on the last page. - `prevCursor` (string, required, nullable) — Pass as `cursor` for the previous page. Null on the first page. - `total` (integer, required, nullable) — Exact count matching the filter. Null unless `include=total`. ## Errors ### 400 List Instruments Request Bad Request Error The request is malformed, or its cursor is not valid for it. - `error` (ErrorBody, required) ### 401 List Instruments Request Unauthorized Error The bearer token is missing or not valid. - `error` (ErrorBody, required) ### 501 List Instruments Request Not Implemented Error Not implemented yet: `search`, `include=facets` and `include=ticker` are published for review. Every other parameter is served. - `error` (ErrorBody, required) ### 503 List Instruments Request Service Unavailable Error A store is temporarily unavailable; retry. - `error` (ErrorBody, required) ## Types ### Facets Counts of matching instruments per dimension, null unless `include=facets`. Each dimension is counted under the request's filters minus that dimension's own filter, so a filter panel keeps showing the alternatives to the choice made in it. Each `value` is what the matching filter takes: `venues` feeds `venueId`, `types` feeds `type`, `baseAssets` feeds `baseAssetId` and `quoteAssets` feeds `quoteAssetId`. Values with no matches are omitted; counts sort descending. - `baseAssets` (list of FacetCount, required) — Matching instruments per base asset: `value` is the asset id, `label` the asset symbol. - `quoteAssets` (list of FacetCount, required) — Matching instruments per quote asset: `value` is the asset id, `label` the asset symbol. - `types` (list of FacetCount, required) — Matching instruments per instrument type: `value` is the type name, `label` is null. - `venues` (list of FacetCount, required) — Matching instruments per venue: `value` is the venue id, `label` the venue code. ### Instrument One market on one venue: a spot pair, a perpetual swap, a dated future, an option or an index. Foreign ids carry their display alias beside them. - `baseAsset` (string, required) — The base asset's symbol, the display alias of `baseAssetId`. - `baseAssetId` (string, required) — The base asset's id. - `contractMultiplier` (string, required) — The contract multiplier: the base-asset quantity one unit of the instrument represents. `"1"` for spot. - `contractValue` (string, required, nullable) — 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. - `expiresAtNs` (string, required, nullable) — When a dated future or option stops trading, in epoch nanoseconds. Null for a product without an expiry. - `feeAsset` (string, required, nullable) — The symbol of the asset trading fees are charged in, the display alias of `feeAssetId`. Null whenever `feeAssetId` is. - `feeAssetId` (string, required, nullable) — The id of the asset trading fees are charged in. Null when unknown. - `instrumentId` (string, required) — The instrument's id. Ids are opaque strings. - `listedAtNs` (string, required, nullable) — When the catalog first knew the instrument (its `createdAt`), in epoch nanoseconds. Null when unknown. - `makerFeeRate` (string, required) — 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. - `minNotional` (string, required, nullable) — The smallest order notional, in the quote asset. Null when the venue states none. - `priceDecimals` (integer, required) — The decimal places needed to render every valid price, derived from `tickSize`. - `priceMax` (string, required, nullable) — The highest price the venue accepts. Null when the venue states none. - `priceMin` (string, required, nullable) — The lowest price the venue accepts. Null when the venue states none. - `qtyDecimals` (integer, required) — The decimal places needed to render every valid quantity, derived from `stepSize`. - `qtyMax` (string, required, nullable) — The largest order quantity. Null when the venue states none. - `qtyMin` (string, required, nullable) — The smallest order quantity. Null when the venue states none. - `quoteAsset` (string, required) — The quote asset's symbol, the display alias of `quoteAssetId`. - `quoteAssetId` (string, required) — The quote asset's id. - `settleAsset` (string, required, nullable) — The settlement asset's symbol, the display alias of `settleAssetId`. Null whenever `settleAssetId` is. - `settleAssetId` (string, required, nullable) — 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. - `settlesAtNs` (string, required, nullable) — When a dated future or option settles, in epoch nanoseconds. Null for a product without a settlement. - `status` (string, required) — 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. - `stepSize` (string, required) — The quantity increment: every valid quantity is a multiple of it. - `symbol` (string, required) — 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. - `takerFeeRate` (string, required) — The taker fee rate as a fraction of the notional. `"0"` when the venue charges none; a rebate is negative. - `tickSize` (string, required) — The price increment: every valid price is a multiple of it. - `ticker` (Ticker, required, nullable) — 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. - `type` (string, required) — 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. - `underlyingInstrumentId` (string, required, nullable) — The id of the instrument a derivative is written on. Null today for every row: the catalog does not state it. - `updatedAtNs` (string, required, nullable) — When the instrument record last changed, as a sequencer timestamp in epoch nanoseconds. Statistics do not move it. Null when unknown. - `venue` (string, required) — The venue's code, the display alias of `venueId`. - `venueId` (string, required) — The venue's id. - `venueSymbol` (string, required) — The venue's own symbol for the instrument, as its API spells it. ### ErrorBody - `code` (string, required) — Machine-readable, UPPER_SNAKE and append-only; tolerate codes you don't know. Branch on this, never on the message. - `message` (string, required) — For display only; its wording may change at any time. - `requestId` (string, required) — The request's id, also sent as X-Request-Id; quote it to support. - `retryable` (boolean, required) — Whether the same request may succeed if retried later. ### FacetCount One value of a facet dimension and how many matching instruments carry it. - `count` (integer, required) — The number of matching instruments with this value. - `label` (string, required, nullable) — The value's display alias: the venue code in `venues`, the asset symbol in `baseAssets` and `quoteAssets`. Null in `types`. - `value` (string, required) — The value, as the matching filter takes it: the venue id in `venues`, the asset id in `baseAssets` and `quoteAssets`, the type name in `types`. ### Ticker 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. - `high24h` (string, required, nullable) — The highest price traded in the last 24 hours; the last price when the window had no trades. Null while the window warms. - `lastPx` (string, required) — The last traded price, as a decimal string. - `low24h` (string, required, nullable) — The lowest price traded in the last 24 hours; the last price when the window had no trades. Null while the window warms. - `pctChange1h` (string, required, nullable) — The change over the last hour as a fraction of the hour's opening price: `"-0.0132"` is -1.32%. `"0"` for an hour with no trades; null while the window warms. - `pctChange24h` (string, required, nullable) — The change over the last 24 hours as a fraction of the window's opening price. `"0"` for a window with no trades; null while the window warms. - `turnover24h` (string, required, nullable) — The quote-asset notional traded in the last 24 hours. Null while the window warms, and null for a shape that cannot be valued in its quote asset (an option, an index). - `volume24h` (string, required, nullable) — The base-asset quantity traded in the last 24 hours. Null while the window warms. - `windowComplete` (boolean, required) — Whether the 24-hour window has a full 24 hours of history behind it. False after a restart until it does; the 24-hour fields are null meanwhile. ## Examples **Response** ```json { "asOfSeqTsNs": "asOfSeqTsNs", "facets": { "baseAssets": [ { "count": 412, "label": "okx", "value": "300" } ], "quoteAssets": [ { "count": 412, "label": "okx", "value": "300" } ], "types": [ { "count": 412, "label": "okx", "value": "300" } ], "venues": [ { "count": 412, "label": "okx", "value": "300" } ] }, "items": [ { "baseAsset": "BTC", "baseAssetId": "1", "contractMultiplier": "1", "contractValue": "100", "expiresAtNs": "1782460800000000000", "feeAsset": "USDT", "feeAssetId": "3", "instrumentId": "1234567", "listedAtNs": "1735689600000000000", "makerFeeRate": "0.001", "minNotional": "5", "priceDecimals": 1, "priceMax": "1000000", "priceMin": "0.1", "qtyDecimals": 2, "qtyMax": "10000", "qtyMin": "0.01", "quoteAsset": "USDT", "quoteAssetId": "3", "settleAsset": "USDT", "settleAssetId": "3", "settlesAtNs": "1782460800000000000", "status": "OPEN", "stepSize": "0.01", "symbol": "OKX@BTC/USDT:USDT", "takerFeeRate": "0.0015", "tickSize": "0.1", "ticker": { "high24h": "64010", "lastPx": "63125.5", "low24h": "61780.5", "pctChange1h": "-0.0132", "pctChange24h": "0.0245", "turnover24h": "9871204.35", "volume24h": "18234.51", "windowComplete": true }, "type": "PERPETUAL_SWAP", "underlyingInstrumentId": "1234560", "updatedAtNs": "1758640000000000000", "venue": "okx", "venueId": "300", "venueSymbol": "BTC-USDT-SWAP" } ], "nextCursor": "nextCursor", "prevCursor": "prevCursor", "total": 1 } ``` **SDK Code** ```python import requests url = "https://api.example.com/instruments" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.example.com/instruments'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.example.com/instruments" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.example.com/instruments") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.example.com/instruments") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.example.com/instruments', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.example.com/instruments"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/instruments")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```