Documentation
Trade on KyanKyan Help Centre

Orderbook Events

Orderbook Events

These events are shared across the orderbook_options, orderbook_perps, and orderbook_maker channels.

All orderbook events deliver orders as arrays for efficient batched delivery.

📘

For details on how order_id relates to trade_id across partial fills and multiple executions, see the Order ID vs Trade ID Guide.

Order Fields

FieldTypeDescription
instrument_namestringInstrument identifier
typestringOrder type (e.g., "good_til_cancelled")
order_idstringUnique order identifier (32 hex characters)
order_statestring"open", "filled", or "cancelled"
pricenumberOrder price
directionstring"buy" or "sell"
post_onlybooleanWhether order is post-only
makerstringMaker's Ethereum address
takerstringTaker's Ethereum address (zero address for new orders)
user_idstringUser identifier
mmpbooleanWhether this is an MMP order
liquidationbooleanWhether this is a liquidation order
creation_timestampnumberOrder creation time in seconds
chain_idnumberBlockchain network identifier
signature_deadlinenumberSignature expiration timestamp
signaturestringCryptographic signature
contractsnumberCanonical order size in base contracts (both options and perpetuals)
filled_contractsnumberCanonical cumulative filled size in base contracts (both options and perpetuals) — the fill-side analog of contracts.
amountnumberPerpetual order size in USD notional. Perpetuals only; emitted alongside contracts.
filled_amountnumberCumulative filled size in the public size unit: contracts for options, USD notional (matching amount) for perpetuals. Prefer filled_contracts.

Both options and perpetual orders carry contracts (canonical size) and filled_contracts (canonical filled size), both in base contracts. Perpetual orders additionally carry the notional amount, and their filled_amount is reported in that same notional unit. New integrations should read contracts / filled_contracts. The notional amount field (and the notional filled_amount for perpetuals) is deprecated and will be removed in a future release as perpetual sizing migrates fully to contracts.

post_order

Emitted when new orders are posted to the orderbook.

{
  "kind": "event",
  "type": "post_order",
  "timestamp_ms": 1677721600000,
  "data": [
    {
      "instrument_name": "BTC_USDC-31OCT25-130000-C",
      "type": "good_til_cancelled",
      "order_id": "abc123def456",
      "order_state": "open",
      "filled_amount": 0,
      "filled_contracts": 0,
      "price": 2500.0,
      "direction": "buy",
      "post_only": true,
      "maker": "0x1234567890abcdef1234567890abcdef12345678",
      "taker": "0x0000000000000000000000000000000000000000",
      "user_id": "trader_001",
      "mmp": false,
      "liquidation": false,
      "creation_timestamp": 1677721600,
      "chain_id": 421614,
      "signature_deadline": 1677721700,
      "signature": "0x...",
      "contracts": 1.5
    }
  ],
  "subscription": {
    "channel": "orderbook_options",
    "query": {
      "instrument_name": "BTC_USDC-31OCT25-130000-C"
    }
  }
}

cancel_order

Emitted when orders are cancelled.

{
  "kind": "event",
  "type": "cancel_order",
  "timestamp_ms": 1677721600000,
  "data": [
    {
      "instrument_name": "BTC_USDC-31OCT25-130000-C",
      "type": "good_til_cancelled",
      "order_id": "abc123def456",
      "order_state": "cancelled",
      "filled_amount": 0,
      "filled_contracts": 0,
      "price": 2640.0,
      "direction": "buy",
      "post_only": false,
      "maker": "0x39ff2600293a6746140c3caaa51bcd62dcb06cbf",
      "taker": "0x0000000000000000000000000000000000000000",
      "user_id": "trader_001",
      "mmp": false,
      "liquidation": false,
      "creation_timestamp": 1677721600,
      "chain_id": 421614,
      "signature_deadline": 1677721700,
      "signature": "0x...",
      "contracts": 4
    }
  ],
  "subscription": {
    "channel": "orderbook_options",
    "query": {
      "instrument_name": "BTC_USDC-31OCT25-130000-C"
    }
  }
}

update_order

Emitted when an order's fill status changes (partial or complete fills).

When emitted:

  • After a partial fill (order remains open with updated filled_amount)
  • After a complete fill (order state changes to filled)
  • When IOC (Immediate-or-Cancel) orders are partially filled and reinstated

Use cases:

  • Update displayed remaining volume for orders in the orderbook
  • Remove fully filled orders from your local orderbook cache
  • Track fill progress for your own orders
{
  "kind": "event",
  "type": "update_order",
  "timestamp_ms": 1677721650000,
  "data": [
    {
      "instrument_name": "BTC_USDC-31OCT25-130000-C",
      "type": "good_til_cancelled",
      "order_id": "abc123def456",
      "order_state": "open",
      "filled_amount": 0.5,
      "filled_contracts": 0.5,
      "price": 2500.0,
      "direction": "buy",
      "post_only": true,
      "maker": "0x1234567890abcdef1234567890abcdef12345678",
      "taker": "0x0000000000000000000000000000000000000000",
      "user_id": "trader_001",
      "mmp": false,
      "liquidation": false,
      "creation_timestamp": 1677721600,
      "chain_id": 421614,
      "signature_deadline": 1677721700,
      "signature": "0x...",
      "contracts": 1.5
    }
  ],
  "subscription": {
    "channel": "orderbook_options",
    "query": {
      "instrument_name": "BTC_USDC-31OCT25-130000-C"
    }
  }
}

Key Fields:

  • order_state: "open" for partial fills, "filled" for complete fills
  • contracts: Original order size in base contracts (never changes; present for both options and perpetuals)
  • filled_contracts: Cumulative filled size in base contracts (both options and perpetuals)
  • filled_amount: Cumulative filled size in the public size unit (contracts for options; USD notional, matching amount, for perpetuals)
  • Remaining volume: contracts - filled_contracts (base contracts, uniform for options and perpetuals)

Handling update_order for orderbook building:

if (event.type === 'update_order') {
  for (const order of event.data) {
    // Base contracts, uniform for options and perpetuals.
    const remainingVolume = order.contracts - order.filled_contracts;

    if (order.order_state === 'filled') {
      // Fully filled - remove from orderbook
      orderbook.delete(order.order_id);
    } else if (order.order_state === 'open') {
      // Partially filled - update remaining volume
      orderbook.set(order.order_id, {
        ...order,
        displayVolume: remainingVolume
      });
    }
  }
}

Order Editing

When an order is edited via PATCH /limit, the original order is cancelled and a new order is created with a new order_id. This produces a cancel_order event for the old order followed by a post_order event for the new order. There is no separate edit_order event type.