Documentation
Trade on KyanKyan Help Centre
Start typing to search…

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"
filled_amountnumberCumulative amount filled so far
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
contractsnumberOrder size for options
amountnumberOrder size for perpetuals

For options orders, use contracts for size. For perpetual orders, use amount.

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,
      "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,
      "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,
      "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
  • filled_amount: Total amount filled so far (cumulative)
  • contracts (options) or amount (perps): Original order size (never changes)
  • Remaining volume: Calculate as contracts - filled_amount or amount - filled_amount

Handling update_order for orderbook building:

if (event.type === 'update_order') {
  for (const order of event.data) {
    const remainingVolume = (order.contracts || order.amount) - order.filled_amount;

    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.

Updated about 15 hours ago