IMMIX Instruments API

openapi: 3.2.0
info:
  title: REST Instruments API
  version: 1.0.0
servers:
- url: https://api.immix.xyz/v1
  description: prod
tags:
- name: Instruments
paths:
  /instruments:
    get:
      operationId: instruments_list
      summary: Search and list instruments
      description: The instruments this environment serves, searched and filtered, sorted by symbol unless `sort` says otherwise. `search` matches word prefixes of the symbol, the venue's own symbol, the type and the id; `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`.
      tags:
      - Instruments
      parameters:
      - name: search
        in: query
        description: 'Case-insensitive word prefixes, matched against the instrument''s words: its symbol''s, the venue''s own symbol''s, its type''s, its id and, for a dated future, its expiry''s (`jun 2027`, `jun27`). Every word sent must be a prefix of one of them: `btc usdt` matches `OKX@BTC/USDT:USDT`, `okx btc perp` the OKX perpetual, `1000` the `1000PEPE` markets and the ids starting `1000`, `perp` every perpetual swap. Anything but ASCII letters and digits separates words and is otherwise ignored, so `btc/usdt` is `btc usdt`, and a search with no ASCII letter or digit filters nothing. Every match is listed: nothing is truncated.'
        required: false
        schema:
          type: string
      - name: symbol
        in: query
        description: 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.
        required: false
        schema:
          type: string
      - name: venueId
        in: query
        description: Only these venue ids; repeat the parameter or comma-separate.
        required: false
        schema:
          type: string
      - name: venueId.notIn
        in: query
        description: Every venue except these ids.
        required: false
        schema:
          type: string
      - name: venue
        in: query
        description: Only these venues, by code (`okx`, `binance_usd-m`), case-insensitive. A code no venue has matches nothing.
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: '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.'
        required: false
        schema:
          $ref: '#/components/schemas/data_instruments_ListInstrumentsRequestTypeItem'
      - name: status
        in: query
        description: '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.'
        required: false
        schema:
          $ref: '#/components/schemas/data_instruments_ListInstrumentsRequestStatusItem'
      - name: baseAssetId
        in: query
        description: Only these base asset ids.
        required: false
        schema:
          type: string
      - name: baseAsset
        in: query
        description: Only these base assets, by symbol (`BTC`), case-insensitive. A symbol no asset has matches nothing.
        required: false
        schema:
          type: string
      - name: quoteAssetId
        in: query
        description: Only these quote asset ids.
        required: false
        schema:
          type: string
      - name: quoteAsset
        in: query
        description: Only these quote assets, by symbol (`USDT`), case-insensitive. A symbol no asset has matches nothing.
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: 'Comma-separated `symbol`, `instrumentId`, `type`, `listedAtNs`, `expiresAtNs`, `lastPx`, `pctChange24h`, `volume24h`, `turnover24h` or `turnoverUsd24h`; prefix `-` for descending. Default `symbol`. `volume24h` is in base units and `turnover24h` in quote units, so neither compares markets of different assets: `-turnoverUsd24h` ranks every market by size. 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 or a USD turnover with no current rate.'
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Page size, 1-100; larger values are clamped. Default 50.
        required: false
        schema:
          type: integer
      - name: cursor
        in: query
        description: '`nextCursor` or `prevCursor` from a previous page, sent with the same filters and sort.'
        required: false
        schema:
          type: string
      - name: include
        in: query
        description: '`total` adds the exact count; `ticker` adds each row''s latest statistics, from the same snapshot the statistics sorts read; `facets` adds counts per venue, type, base and quote asset. Each facet ignores its own dimension''s filter and applies every other filter and the search, so a filter panel keeps its alternatives: with `type=SPOT`, `types` still counts every type the rest of the query matches, `OPTION` included, while `venues` and the asset facets count spot rows only. The count of what you chose is its own entry: `SPOT` in `types`. Ask for several at once by comma-separating them, `include=total,facets,ticker`, or by repeating the parameter.'
        required: false
        schema:
          $ref: '#/components/schemas/data_instruments_ListInstrumentsRequestIncludeItem'
      - name: X-Request-Id
        in: header
        description: '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.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A page of instruments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_InstrumentPage'
        '400':
          description: The request is malformed, or its cursor is not valid for it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_Error'
        '401':
          description: The bearer token is missing or not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_Error'
        '503':
          description: A store is temporarily unavailable; retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_Error'
      security:
      - bearerAuth: []
  /instruments/{instrumentId}:
    get:
      operationId: instruments_get
      summary: Get an instrument
      description: '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=`.'
      tags:
      - Instruments
      parameters:
      - name: instrumentId
        in: path
        description: The instrument id.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: '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.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The instrument.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_Instrument'
        '400':
          description: The request is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_Error'
        '401':
          description: The bearer token is missing or not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_Error'
        '404':
          description: No such resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_Error'
        '503':
          description: A store is temporarily unavailable; retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_Error'
      security:
      - bearerAuth: []
components:
  schemas:
    data_instruments_ListInstrumentsRequestStatusItemZero:
      type: string
      enum:
      - LISTED
      - OPEN
      - SUSPENDED
      - SETTLED
      - DELISTED
      title: ListInstrumentsRequestStatusItemZero
    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: '#/components/schemas/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
      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.'
      title: Instrument
    data_instruments_ListInstrumentsRequestIncludeItem:
      type: string
      enum:
      - total
      - facets
      - ticker
      title: ListInstrumentsRequestIncludeItem
    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
    data_instruments_ListInstrumentsRequestTypeItemZero:
      type: string
      enum:
      - SPOT
      - FUTURES
      - INVERSE_FUTURES
      - QUANTO_FUTURES
      - PERPETUAL_SWAP
      - INVERSE_PERPETUAL_SWAP
      - QUANTO_PERPETUAL_SWAP
      - OPTION
      - INVERSE_OPTION
      - INDEX
      title: ListInstrumentsRequestTypeItemZero
    data_ErrorBody:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable, UPPER_SNAKE and append-only; tolerate codes you don't know. Branch on this, never on the message.
        message:
          type: string
          description: For display only; its wording may change at any time.
        retryable:
          type: boolean
          description: 'Whether sending the identical request again, after `Retry-After` or a short pause, can succeed with nothing else changed. `false` where something must change first: the request, the caller''s standing, or the platform''s own records or deployment.'
        requestId:
          type: string
          description: The request's id, also sent as X-Request-Id; quote it to support.
      required:
      - code
      - message
      - retryable
      - requestId
      title: ErrorBody
    data_instruments_ListInstrumentsRequestTypeItem:
      oneOf:
      - $ref: '#/components/schemas/data_instruments_ListInstrumentsRequestTypeItemZero'
      - type: string
      title: ListInstrumentsRequestTypeItem
    data_InstrumentPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/data_Instrument'
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass as `cursor` for the next page. Null on the last page.
        prevCursor:
          type:
          - string
          - 'null'
          description: Pass as `cursor` for the previous page. Null on the first page.
        total:
          type:
          - integer
          - 'null'
          description: Exact count matching the filter. Null unless `include=total`.
        facets:
          oneOf:
          - $ref: '#/components/schemas/data_Facets'
          - type: 'null'
        asOfSeqTsNs:
          type:
          - string
          - 'null'
          pattern: ^[0-9]+$
          description: The sequencer timestamp (epoch-ns) the data is complete through; also sent as X-Immix-As-Of-Seq-Ts. Null when unknown.
      required:
      - items
      - nextCursor
      - prevCursor
      - total
      - facets
      - asOfSeqTsNs
      description: A page of instruments.
      title: InstrumentPage
    data_Facets:
      type: object
      properties:
        venues:
          type: array
          items:
            $ref: '#/components/schemas/data_FacetCount'
          description: 'Matching instruments per venue, counted without the venue filters (`venueId`, `venue`, `venueId.notIn`): `value` is the venue id, `label` the venue code.'
        types:
          type: array
          items:
            $ref: '#/components/schemas/data_FacetCount'
          description: 'Matching instruments per instrument type, counted without the `type` filter: `value` is the type name, `label` is null.'
        baseAssets:
          type: array
          items:
            $ref: '#/components/schemas/data_FacetCount'
          description: 'Matching instruments per base asset, counted without the base asset filters (`baseAssetId`, `baseAsset`): `value` is the asset id, `label` the asset symbol.'
        quoteAssets:
          type: array
          items:
            $ref: '#/components/schemas/data_FacetCount'
          description: 'Matching instruments per quote asset, counted without the quote asset filters (`quoteAssetId`, `quoteAsset`): `value` is the asset id, `label` the asset symbol.'
      required:
      - venues
      - types
      - baseAssets
      - quoteAssets
      description: '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: with `type=SPOT`, `types` counts every type the rest of the query matches, and the other three count spot instruments. 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; within a dimension the values sort by count, most first, then by value, ids as numbers and type names as text.'
      title: Facets
    data_FacetCount:
      type: object
      properties:
        value:
          type: string
          description: '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`.'
        label:
          type:
          - string
          - 'null'
          description: 'The value''s display alias: the venue code in `venues`, the asset symbol in `baseAssets` and `quoteAssets`. Null in `types`.'
        count:
          type: integer
          description: The number of matching instruments with this value.
      required:
      - value
      - label
      - count
      description: One value of a facet dimension and how many matching instruments carry it.
      title: FacetCount
    data_Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/data_ErrorBody'
        currentVersion:
          type: string
          pattern: ^-?[0-9]+$
          description: 'On a 412 `VERSION_CONFLICT` from a conditional write: the row''s current version (the `ETag` carries the same token); re-read, reapply, retry. No operation of this API is a conditional write yet, so no response carries it.'
      required:
      - error
      description: Every non-2xx response carries this envelope.
      title: Error
    data_instruments_ListInstrumentsRequestStatusItem:
      oneOf:
      - $ref: '#/components/schemas/data_instruments_ListInstrumentsRequestStatusItemZero'
      - type: string
      title: ListInstrumentsRequestStatusItem
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer