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

# Get an instrument

GET /instruments/{instrumentId}

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=`.

Reference: https://docs.immix.xyz/api-reference/rest-api/instruments/get

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `instrumentId` (string, required) — The instrument id.

## Response

### 200

The instrument.

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

## Errors

### 400 Get Instruments Request Bad Request Error

The request is malformed.

- `error` (ErrorBody, required)

### 401 Get Instruments Request Unauthorized Error

The bearer token is missing or not valid.

- `error` (ErrorBody, required)

### 404 Get Instruments Request Not Found Error

No such resource.

- `error` (ErrorBody, required)

### 503 Get Instruments Request Service Unavailable Error

A store is temporarily unavailable; retry.

- `error` (ErrorBody, required)

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

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

## Examples

**Response**

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

**SDK Code**

```python
import requests

url = "https://api.example.com/instruments/instrumentId"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.example.com/instruments/instrumentId';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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/instrumentId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	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/instrumentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.example.com/instruments/instrumentId")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.example.com/instruments/instrumentId', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/instruments/instrumentId");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/instruments/instrumentId")! 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()
```