Fills

A Fill is an immutable record of an executed quantity. It proves matching occurred; it does not by itself prove final settlement or redemption.

Endpoints

Both endpoints require canonical API-key request authentication and orders:read or an approved equivalent scope.

Fill schema

{
  "data": {
    "fill_id": "fill_demo_001",
    "trade_id": "trade_demo_771",
    "order_id": "ord_demo_001",
    "client_order_id": "client_demo_20260831_001",
    "account_id": "acct_demo_001",
    "market_id": "mkt_demo_001",
    "outcome_id": "out_demo_yes_001",
    "side": "BUY",
    "price": "0.6400",
    "quantity": "100.00",
    "notional": "64.00",
    "liquidity_role": "maker",
    "fee": {
      "amount": "0.20",
      "asset_id": "asset_demo_collateral_001",
      "rate": "0.003125",
      "schedule_id": "fees_demo_001",
      "schedule_version": "1"
    },
    "counterparty_type": "anonymous_venue_participant",
    "engine_sequence": 992011,
    "matched_at": "2026-08-31T12:00:03.100Z",
    "matched_at_ts_ms": 1788350403100,
    "published_at": "2026-08-31T12:00:03.130Z",
    "settlement_id": "set_demo_001",
    "settlement_state": "pending",
    "adjustment_ids": [],
    "schema_version": "1.0"
  },
  "meta": {
    "request_id": "req_demo_fill_001",
    "published_at": "2026-08-31T12:00:03.130Z",
    "schema_version": "1.0"
  }
}

Maker/taker is assigned per Fill. A single order can be maker for one Fill and taker for another after an amend/replace or venue-specific transition; clients MUST sum actual Fill fee records instead of inferring fees from initial order flags.

Partial fills and average price

One Order may produce many Fills at different prices. filled_quantity and average_fill_price on the Order are projections calculated from its immutable Fills. Account reconciliation treats the Fill list as the execution source of truth and verifies:

order.filled_quantity = sum(fill.quantity + signed adjustment.quantity_delta)
order.average_fill_price = sum(fill.price * fill.quantity) / sum(fill.quantity)

Implementations use fixed-point arithmetic and the Market’s declared scales; the formula above is conceptual, not permission to use binary floats.

Cancel races

Cancellation has an engine cutoff. A Fill whose engine_sequence precedes or equals the accepted cutoff remains valid even if its event is delivered after the cancel HTTP response. Clients reconcile by sequence and IDs, never by wall-clock arrival order. A Fill after the authoritative cutoff is an incident and MUST NOT be hidden by rewriting history.

Adjustments and corrections

Fills are never edited or deleted. If an operational or settlement correction is required, the detail endpoint links append-only adjustment records containing:

• adjustment_id, fill_id, and adjustment type;
• signed quantity/notional/fee deltas as decimal strings;
• reason code and human rationale;
• evidence/external reference IDs;
• authorized actor and approval record;
• effective and published timestamps;
• supersedes_adjustment_id when correcting an adjustment.

An adjustment does not pretend a trade never happened. Position, balance, fee, and settlement projections expose which adjustment IDs they consumed.

List and history

GET /fills supports order_id, market_id, outcome_id, side, liquidity_role, settlement_state, matched_after, matched_before, engine_sequence_after, cursor, and limit. Default order is (engine_sequence, fill_id) descending.

For gap reconciliation, a client SHOULD take an account snapshot, then request Fills after the snapshot’s engine sequence, deduplicate by fill_id, and apply only unseen adjustment IDs. WebSocket delivery may duplicate events and is not a substitute for REST reconciliation.

Privacy

Private Fill responses identify only the authenticated account’s role. Public trade endpoints use venue-permitted anonymized trade records and never expose another participant’s account, order, signature, or API credential.