IMMIX Executions API

openapi: 3.2.0
info:
  title: REST Executions API
  version: 1.0.0
  description: Fills, joined to their order by `orderId`.
servers:
- url: https://api.immix.xyz/v1
  description: prod
tags:
- name: Executions
  description: Fills, joined to their order by `orderId`.
paths:
  /executions:
    get:
      operationId: executions_list
      summary: List executions
      description: 'Lists the organisation''s fills — one immutable economic event each; a bust or a correction is its own row — including fills not yet attributed to an order; `orderId` narrows to one order''s. An order''s `cumQty` and `avgPx` derive from these. Newest first: by `executionId`, descending.'
      tags:
      - Executions
      parameters:
      - name: orderId
        in: query
        description: Only one order's fills; an order outside your organisation yields an empty collection, like an absent one.
        required: false
        schema:
          type: string
          pattern: ^[1-9][0-9]*$
      - name: limit
        in: query
        description: Page size, 1-100; larger values are clamped. Without it the whole collection is served as one page.
        required: false
        schema:
          type: integer
          minimum: 1
      - name: cursor
        in: query
        description: '`nextCursor` or `prevCursor` from a previous page, sent with the same filters. One that does not decode, or that came from another query, is refused 400 `INVALID_CURSOR`: drop it and fetch the first page.'
        required: false
        schema:
          type: string
          maxLength: 2048
      - name: include
        in: query
        description: '`total` adds the exact number of rows matching the filters.'
        required: false
        schema:
          $ref: '#/components/schemas/executions_ListExecutionsRequestIncludeItem'
      - 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 the rows inside the principal's org, in the operation's order — all of them unless `limit` is sent; the position it was read at rides the body and the headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/executions_ListExecutionsResponse'
        '400':
          description: 'The request''s shape is wrong: a non-positive id, an unknown `view` or filter value, a query string that does not decode, a query parameter the operation does not take, or a cursor that does not decode or came from another query (`INVALID_CURSOR`). No position rides a refusal that consulted no state.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No bearer token, or one that does not verify.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Authenticated, but not admitted. `NOT_REGISTERED`: no row and no open invitation at your verified address (ask to be invited), an unknown organisation, or a row nobody has claimed (an administrator admits it; no invitation binds a held subject). `EMAIL_UNVERIFIED`: verify your address, then sign in again. `INVITATION_EXPIRED`: an administrator re-invites. `FORBIDDEN_PRINCIPAL`: no `org_id`, a non-ASCII ref, a disabled user, a binding with no user. `ORG_NOT_ACTIVE`: suspended, pending or retired. The record owners'' 403s carry the position header and replay with `Idempotent-Replay`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: This member is still catching up; retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
  /executions/{id}:
    get:
      operationId: executions_get
      summary: Get an execution
      description: Serves one execution of the organisation; any other id is 404. Executions carry no version and no `ETag`.
      tags:
      - Executions
      parameters:
      - name: id
        in: path
        description: The execution's id — a positive 64-bit integer as decimal digits.
        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: One fill — an immutable economic event; a bust or a correction is its own row. Executions carry no version, so no `ETag`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/executions_GetExecutionsResponse'
        '400':
          description: 'The request''s shape is wrong: a non-positive id, an unknown `view` or filter value, a query string that does not decode, a query parameter the operation does not take, or a cursor that does not decode or came from another query (`INVALID_CURSOR`). No position rides a refusal that consulted no state.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No bearer token, or one that does not verify.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Authenticated, but not admitted. `NOT_REGISTERED`: no row and no open invitation at your verified address (ask to be invited), an unknown organisation, or a row nobody has claimed (an administrator admits it; no invitation binds a held subject). `EMAIL_UNVERIFIED`: verify your address, then sign in again. `INVITATION_EXPIRED`: an administrator re-invites. `FORBIDDEN_PRINCIPAL`: no `org_id`, a non-ASCII ref, a disabled user, a binding with no user. `ORG_NOT_ACTIVE`: suspended, pending or retired. The record owners'' 403s carry the position header and replay with `Idempotent-Replay`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such row in your organisation — another organisation's row is indistinguishable from an absent one. The position header says as of when.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: This member is still catching up; retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth: []
components:
  schemas:
    executions_GetExecutionsResponse:
      type: object
      properties:
        executionId:
          type: string
          pattern: ^-?[0-9]+$
          description: int64 as a decimal JSON string
        orderId:
          type: string
          pattern: ^-?[0-9]+$
          description: 0 = unattributed (discovered); set otherwise. int64 as a decimal JSON string
        orgId:
          type: integer
        accountId:
          type: integer
        credentialId:
          type: integer
        instrumentId:
          type: string
          pattern: ^-?[0-9]+$
          description: int64 as a decimal JSON string
        bookId:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+$
          description: Denormalized from the order at recording (0 = none / discovered); re-stamped by attribution. int64 as a decimal JSON string
        side:
          $ref: '#/components/schemas/ExecutionRecordedSide'
          description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
        kind:
          $ref: '#/components/schemas/ExecutionRecordedKind'
          description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
        liquidity:
          $ref: '#/components/schemas/ExecutionRecordedLiquidity'
          description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
        fillQty:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          maxLength: 64
          description: 'Always positive; kind gives the sign of its effect (BUST reverses). money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value''s own scale — every fractional digit that scale states, trailing zeros included; never raw'
        fillPx:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          maxLength: 64
          description: 'money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value''s own scale — every fractional digit that scale states, trailing zeros included; never raw'
        fee:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          maxLength: 64
          description: 'money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value''s own scale — every fractional digit that scale states, trailing zeros included; never raw; null when the 0 sentinel means unset'
        feeAssetId:
          type:
          - integer
          - 'null'
        fillTsNs:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+$
          description: int64 as a decimal JSON string
        venueTsNs:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+$
          description: int64 as a decimal JSON string
        venueTradeId:
          type: string
          description: The venue execution id — the dedup key's third component.
        externalRef:
          type: string
          description: The venue order id as carried by the fill event; the auto-attribution join key for discovered rows (both facts carry it).
        globalSequence:
          $ref: '#/components/schemas/GlobalSequenceValue'
        unscaled:
          type: boolean
          description: 'Never present since 0.3.3: every money value on this API states its own scale on the wire — a policy amount or cap since 0.3.3, an order''s and an execution''s since 0.3.2, a balance''s since 0.3.1 — so a row is never served raw, whether or not this member holds the asset or instrument it references. Kept, deprecated, so a client generated from 0.3.2 still compiles; it goes at the next major.'
          deprecated: true
      required:
      - executionId
      - orderId
      - orgId
      - accountId
      - credentialId
      - instrumentId
      - side
      - kind
      - liquidity
      - fillQty
      - fillPx
      - venueTradeId
      - externalRef
      - globalSequence
      title: GetExecutionsResponse
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
        currentVersion:
          type: string
          pattern: ^-?[0-9]+$
          description: 'On 412 `VERSION_CONFLICT`, or `CONFIG_SEQ_CONFLICT` on an algo instance''s config write: the row''s current version (the `ETag` carries the same token) — re-read, reapply, retry.'
      required:
      - error
      description: 'The one error envelope, on every refusal: error.code is the machine surface, error.message display text, error.requestId the request''s id and error.retryable whether a plain retry can succeed. A 412 adds currentVersion.'
      title: Error
    executions_ListExecutionsRequestIncludeItem:
      type: string
      enum:
      - total
      title: ListExecutionsRequestIncludeItem
    ExecutionRecordedKind:
      type: string
      enum:
      - UNKNOWN
      - FILL
      - BUST
      - CORRECTION
      description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
      title: ExecutionRecordedKind
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          description: 'The code to branch on — stable and append-only: treat one you do not know by its HTTP status. The gateway''s:


            - 400: `MALFORMED_REQUEST`, `MISSING_IDEMPOTENCY_KEY`, `INVALID_IDEMPOTENCY_KEY`, `INVALID_IF_MATCH`, `INVALID_CURSOR`

            - 401: `UNAUTHENTICATED`

            - 403: `FORBIDDEN_PRINCIPAL`, `NOT_REGISTERED`, `INVITATION_EXPIRED`, `EMAIL_UNVERIFIED`, `ORG_NOT_ACTIVE`, `CAPABILITY_DENIED`, `AWAITING_ADMISSION`

            - 404: `NOT_FOUND`, `UNKNOWN_OPERATION`, `ROUTE_NOT_FOUND` (no route answers the path)

            - 405: `METHOD_NOT_ALLOWED`

            - 409: `IDEMPOTENCY_KEY_REUSED`, `INTAKE_KEY_REUSED`

            - 413: `TOO_LARGE`, `PAYLOAD_TOO_LARGE`, `DOCUMENT_TOO_LARGE`

            - 422: a reference this member will not send: `INSTRUMENT_NOT_LIVE`, `ACCOUNT_NOT_ACTIVE` (`POST /orders`), `REFERENCE_UNKNOWN_INSTRUMENT`, `REFERENCE_INSTRUMENT_NOT_LIVE`, `REFERENCE_UNKNOWN_ACCOUNT` (an algo document); `VENUE_UNSUPPORTED`; `SCALE_UNKNOWN` (retired at `0.3.4`)

            - 428: `PRECONDITION_REQUIRED`

            - 429: `INBOX_FULL`, `IN_FLIGHT_FULL`, `RATE_LIMITED`

            - 500: `INTERRUPTED`, `INTERNAL_ERROR`, `PROJECTION_MISS`

            - 503: `NOT_PRIMED`, `NOT_SERVING`, `OWNER_ABSENT`, `INTAKE_UNAVAILABLE`, `BALANCES_UNAVAILABLE`, `ALGOS_UNAVAILABLE`, `TICKETS_UNAVAILABLE`, `INVITATIONS_UNAVAILABLE`, `REGISTRATION_PENDING`, `LOST`, `REJECTED_NOT_REGISTERED`, `REJECTED_NOT_ACTIVE`


            The record owners'' refusals ride verbatim — `OrgRegisterRejected.reason`, `OrderRejected.reason` and `AlgoRejected.reason` list them; the guide maps each to its status.'
        message:
          type: string
          description: For display only; its wording may change at any time.
        requestId:
          type: string
          description: The request's id, also sent as X-Request-Id; quote it to support.
        retryable:
          type: boolean
          description: 'Whether sending the identical request again, its `Idempotency-Key` included, after `Retry-After` or a short pause, can succeed with nothing else changed. `false` where something must change first: the request, its key, its precondition, the caller''s standing, or the platform''s own records or deployment. A refusal the record owner judged is always `false`: it is the recorded answer to its key, which replays it.'
      required:
      - code
      - message
      - requestId
      - retryable
      description: What a refusal states. Since `0.12.0` every refusal carries all four members; a member below it sends `code`, sometimes `message`, and neither of the others.
      title: ErrorBody
    GlobalSequenceValue:
      type: string
      pattern: ^[0-9]+$
      description: The position as a decimal string — the last change this member had applied, orders, balance readings and algo instances included.
      title: GlobalSequenceValue
    ExecutionRecordedSide:
      type: string
      enum:
      - UNKNOWN
      - BUY
      - SELL
      description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
      title: ExecutionRecordedSide
    ExecutionRecorded:
      type: object
      properties:
        executionId:
          type: string
          pattern: ^-?[0-9]+$
          description: int64 as a decimal JSON string
        orderId:
          type: string
          pattern: ^-?[0-9]+$
          description: 0 = unattributed (discovered); set otherwise. int64 as a decimal JSON string
        orgId:
          type: integer
        accountId:
          type: integer
        credentialId:
          type: integer
        instrumentId:
          type: string
          pattern: ^-?[0-9]+$
          description: int64 as a decimal JSON string
        bookId:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+$
          description: Denormalized from the order at recording (0 = none / discovered); re-stamped by attribution. int64 as a decimal JSON string
        side:
          $ref: '#/components/schemas/ExecutionRecordedSide'
          description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
        kind:
          $ref: '#/components/schemas/ExecutionRecordedKind'
          description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
        liquidity:
          $ref: '#/components/schemas/ExecutionRecordedLiquidity'
          description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
        fillQty:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          maxLength: 64
          description: 'Always positive; kind gives the sign of its effect (BUST reverses). money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value''s own scale — every fractional digit that scale states, trailing zeros included; never raw'
        fillPx:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          maxLength: 64
          description: 'money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value''s own scale — every fractional digit that scale states, trailing zeros included; never raw'
        fee:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          maxLength: 64
          description: 'money (a Decimal on the wire: a scaled integer with its own scale), served as an exact decimal string at the value''s own scale — every fractional digit that scale states, trailing zeros included; never raw; null when the 0 sentinel means unset'
        feeAssetId:
          type:
          - integer
          - 'null'
        fillTsNs:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+$
          description: int64 as a decimal JSON string
        venueTsNs:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+$
          description: int64 as a decimal JSON string
        venueTradeId:
          type: string
          description: The venue execution id — the dedup key's third component.
        externalRef:
          type: string
          description: The venue order id as carried by the fill event; the auto-attribution join key for discovered rows (both facts carry it).
      required:
      - executionId
      - orderId
      - orgId
      - accountId
      - credentialId
      - instrumentId
      - side
      - kind
      - liquidity
      - fillQty
      - fillPx
      - venueTradeId
      - externalRef
      title: ExecutionRecorded
    ExecutionRecordedLiquidity:
      type: string
      enum:
      - UNKNOWN
      - MAKER
      - TAKER
      description: 'UNKNOWN is the unset sentinel: outputs only — as input, omit the field instead; explicit UNKNOWN refuses 400. The value set is append-only: a consumer READING this field treats an unknown name as UNKNOWN, never as an error; as input an unknown name refuses 400 — the parse is strict'
      title: ExecutionRecordedLiquidity
    executions_ListExecutionsResponse:
      type: object
      properties:
        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`.
        globalSequence:
          $ref: '#/components/schemas/GlobalSequenceValue'
        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.
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExecutionRecorded'
        unscaled:
          type: boolean
          description: 'Never present since 0.3.2: an execution states its own scales, so no item is ever served raw. Kept, deprecated, so a client generated from 0.3.1 still compiles.'
          deprecated: true
      required:
      - nextCursor
      - prevCursor
      - total
      - globalSequence
      - asOfSeqTsNs
      - items
      title: ListExecutionsResponse
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer