Instrument

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/immix/json-schema/immix-data-instrument-schema.json",
  "title": "Instrument",
  "description": "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.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/immix-rest-openapi.json#/components/schemas/data_Instrument",
  "type": "object",
  "properties": {
    "instrumentId": {
      "type": "string",
      "description": "The instrument's id. Ids are opaque strings."
    },
    "symbol": {
      "type": "string",
      "description": "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."
    },
    "venueId": {
      "type": "string",
      "description": "The venue's id."
    },
    "venue": {
      "type": "string",
      "description": "The venue's code, the display alias of `venueId`."
    },
    "venueSymbol": {
      "type": "string",
      "description": "The venue's own symbol for the instrument, as its API spells it."
    },
    "type": {
      "type": "string",
      "description": "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."
    },
    "status": {
      "type": "string",
      "description": "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."
    },
    "baseAssetId": {
      "type": "string",
      "description": "The base asset's id."
    },
    "baseAsset": {
      "type": "string",
      "description": "The base asset's symbol, the display alias of `baseAssetId`."
    },
    "quoteAssetId": {
      "type": "string",
      "description": "The quote asset's id."
    },
    "quoteAsset": {
      "type": "string",
      "description": "The quote asset's symbol, the display alias of `quoteAssetId`."
    },
    "settleAssetId": {
      "type": [
        "string",
        "null"
      ],
      "description": "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."
    },
    "settleAsset": {
      "type": [
        "string",
        "null"
      ],
      "description": "The settlement asset's symbol, the display alias of `settleAssetId`. Null whenever `settleAssetId` is."
    },
    "feeAssetId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The id of the asset trading fees are charged in. Null when unknown."
    },
    "feeAsset": {
      "type": [
        "string",
        "null"
      ],
      "description": "The symbol of the asset trading fees are charged in, the display alias of `feeAssetId`. Null whenever `feeAssetId` is."
    },
    "contractMultiplier": {
      "type": [
        "string",
        "null"
      ],
      "description": "The contract multiplier: the base-asset quantity one unit of the instrument represents. Null where the catalog states none: spot on most venues (one unit is one of the base asset), and inverse futures and inverse perpetual swaps, whose size is `contractValue`."
    },
    "contractValue": {
      "type": [
        "string",
        "null"
      ],
      "description": "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."
    },
    "tickSize": {
      "type": "string",
      "description": "The price increment: every valid price is a multiple of it."
    },
    "stepSize": {
      "type": "string",
      "description": "The quantity increment: every valid quantity is a multiple of it."
    },
    "priceMin": {
      "type": [
        "string",
        "null"
      ],
      "description": "The lowest price the venue accepts. Null when the venue states none."
    },
    "priceMax": {
      "type": [
        "string",
        "null"
      ],
      "description": "The highest price the venue accepts. Null when the venue states none."
    },
    "qtyMin": {
      "type": [
        "string",
        "null"
      ],
      "description": "The smallest order quantity. Null when the venue states none."
    },
    "qtyMax": {
      "type": [
        "string",
        "null"
      ],
      "description": "The largest order quantity. Null when the venue states none."
    },
    "minNotional": {
      "type": [
        "string",
        "null"
      ],
      "description": "The smallest order notional, in the quote asset. Null when the venue states none."
    },
    "priceDecimals": {
      "type": "integer",
      "description": "The decimal places needed to render every valid price, derived from `tickSize`."
    },
    "qtyDecimals": {
      "type": "integer",
      "description": "The decimal places needed to render every valid quantity, derived from `stepSize`."
    },
    "makerFeeRate": {
      "type": "string",
      "description": "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."
    },
    "takerFeeRate": {
      "type": "string",
      "description": "The taker fee rate as a fraction of the notional. `\"0\"` when the venue charges none; a rebate is negative."
    },
    "underlyingInstrumentId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The id of the instrument a derivative is written on. Null today for every row: the catalog does not state it."
    },
    "listedAtNs": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9]+$",
      "description": "When the catalog first knew the instrument (its `createdAt`), in epoch nanoseconds. Null when unknown."
    },
    "expiresAtNs": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9]+$",
      "description": "When a dated future or option stops trading, in epoch nanoseconds. Null for a product without an expiry."
    },
    "settlesAtNs": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9]+$",
      "description": "When a dated future or option settles, in epoch nanoseconds. Null for a product without a settlement."
    },
    "updatedAtNs": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9]+$",
      "description": "When the instrument record last changed, as a sequencer timestamp in epoch nanoseconds. Statistics do not move it. Null when unknown."
    },
    "ticker": {
      "oneOf": [
        {
          "$ref": "#/$defs/data_Ticker"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "instrumentId",
    "symbol",
    "venueId",
    "venue",
    "venueSymbol",
    "type",
    "status",
    "baseAssetId",
    "baseAsset",
    "quoteAssetId",
    "quoteAsset",
    "settleAssetId",
    "settleAsset",
    "feeAssetId",
    "feeAsset",
    "contractMultiplier",
    "contractValue",
    "tickSize",
    "stepSize",
    "priceMin",
    "priceMax",
    "qtyMin",
    "qtyMax",
    "minNotional",
    "priceDecimals",
    "qtyDecimals",
    "makerFeeRate",
    "takerFeeRate",
    "underlyingInstrumentId",
    "listedAtNs",
    "expiresAtNs",
    "settlesAtNs",
    "updatedAtNs",
    "ticker"
  ],
  "$defs": {
    "data_Ticker": {
      "type": "object",
      "properties": {
        "lastPx": {
          "type": "string",
          "description": "The last traded price, as a decimal string."
        },
        "pctChange1h": {
          "type": [
            "string",
            "null"
          ],
          "description": "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": {
          "type": [
            "string",
            "null"
          ],
          "description": "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."
        },
        "volume24h": {
          "type": [
            "string",
            "null"
          ],
          "description": "The base-asset quantity traded in the last 24 hours. Null while the window warms."
        },
        "turnover24h": {
          "type": [
            "string",
            "null"
          ],
          "description": "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)."
        },
        "turnoverUsd24h": {
          "type": [
            "string",
            "null"
          ],
          "description": "`turnover24h` valued in USD at the quote asset's current USD rate: the last 24 hours of quote turnover at today's rate, an approximation. The one statistic comparable across quote assets, so `sort=-turnoverUsd24h` ranks markets of every quote by size. Null whenever `turnover24h` is, and when no USD rate is current for the quote asset; `\"0\"` for a window with no trades."
        },
        "high24h": {
          "type": [
            "string",
            "null"
          ],
          "description": "The highest price traded in the last 24 hours; the last price when the window had no trades. Null while the window warms."
        },
        "low24h": {
          "type": [
            "string",
            "null"
          ],
          "description": "The lowest price traded in the last 24 hours; the last price when the window had no trades. Null while the window warms."
        },
        "windowComplete": {
          "type": "boolean",
          "description": "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."
        }
      },
      "required": [
        "lastPx",
        "pctChange1h",
        "pctChange24h",
        "volume24h",
        "turnover24h",
        "turnoverUsd24h",
        "high24h",
        "low24h",
        "windowComplete"
      ],
      "description": "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.",
      "title": "Ticker"
    }
  }
}