Order Events

WebSocket order event types and structures

Event Types

All order events follow this structure:

type OrderEventType = {
  event: EventType
  data: EventData
}

enum EventType {
  OrderCreated = 'order_created',
  OrderInvalid = 'order_invalid',
  OrderBalanceChange = 'order_balance_change',
  OrderAllowanceChange = 'order_allowance_change',
  OrderFilled = 'order_filled',
  OrderFilledPartially = 'order_filled_partially',
  OrderCancelled = 'order_cancelled',
  OrderSecretShared = 'secret_shared'
}

order_created

Emitted when a new order is created and broadcasted.

Event Structure

{
  event: 'order_created',
  data: {
    srcChainId: NetworkEnum
    dstChainId: NetworkEnum
    orderHash: string
    order: LimitOrderV4Struct
    extension: string
    signature: string
    isMakerContract: boolean
    quoteId: string
    merkleLeaves: string[]
    secretHashes: string[]
  }
}

Fields

srcChainId · NetworkEnum

Source chain ID

dstChainId · NetworkEnum

Destination chain ID

orderHash · string

Unique order hash

order · LimitOrderV4Struct

Order structure (maker, receiver, maker asset, taker asset, maker traits, etc.)

extension · string

Encoded order extension data

signature · string

Order signature

isMakerContract · boolean

Whether maker is a smart contract

quoteId · string

Quote ID used for order creation

merkleLeaves · string[]

Merkle leaves for multi-fill orders (empty for single fill)

secretHashes · string[]

Hashes of secrets (empty array if only one secret)

Example

ws.order.onOrderCreated((data) => {
  console.log(`New order created: ${data.orderHash}`)
  console.log(`  Quote: ${data.quoteId}`)
  console.log(`  From: ${data.srcChainId} → ${data.dstChainId}`)
  console.log(`  Secrets: ${data.secretHashes.length || 1}`)
})

order_filled

Emitted when an order is completely filled.

Event Structure

{
  event: 'order_filled',
  data: {
    orderHash: string
  }
}

Example

ws.order.onOrderFilled((data) => {
  console.log(`Order filled: ${data.orderHash}`)
  // Order is complete, swap executed successfully
})

order_filled_partially

Emitted when an order is partially filled.

Event Structure

{
  event: 'order_filled_partially',
  data: {
    orderHash: string
    remainingMakerAmount: string
  }
}

Fields

orderHash · string

Order hash

remainingMakerAmount · string

Remaining amount to be filled (in wei/smallest unit)

Example

ws.order.onOrderFilledPartially((data) => {
  console.log(`Partial fill: ${data.orderHash}`)
  console.log(`  Remaining: ${data.remainingMakerAmount}`)
  
  // Calculate fill percentage
  const filled = BigInt(originalAmount) - BigInt(data.remainingMakerAmount)
  const percentage = (Number(filled) / Number(originalAmount)) * 100
  console.log(`  ${percentage.toFixed(2)}% filled`)
})

order_cancelled

Emitted when an order is cancelled.

Event Structure

{
  event: 'order_cancelled',
  data: {
    orderHash: string
    remainingMakerAmount: string
  }
}

Fields

orderHash · string

Order hash

remainingMakerAmount · string

Amount that was not filled before cancellation

Example

ws.order.onOrderCancelled((data) => {
  console.log(`Order cancelled: ${data.orderHash}`)
  console.log(`  Unfilled amount: ${data.remainingMakerAmount}`)
})

order_invalid

Emitted when an order becomes invalid (e.g., insufficient balance or allowance).

Event Structure

{
  event: 'order_invalid',
  data: {
    orderHash: string
  }
}

Example

ws.order.onOrderInvalid((data) => {
  console.log(`Order invalid: ${data.orderHash}`)
  // Check balance and allowance
})

order_balance_change

Emitted when the maker’s token balance changes.

Event Structure

{
  event: 'order_balance_change',
  data: {
    orderHash: string
    remainingMakerAmount: string
    balance: string
  }
}

Fields

orderHash · string

Order hash

remainingMakerAmount · string

Remaining amount to fill

balance · string

Current maker token balance

Example

ws.order.onOrderBalanceChange((data) => {
  console.log(`Balance changed for ${data.orderHash}`)
  console.log(`  Balance: ${data.balance}`)
  console.log(`  Remaining: ${data.remainingMakerAmount}`)
})

order_allowance_change

Emitted when the maker’s token allowance changes.

Event Structure

{
  event: 'order_allowance_change',
  data: {
    orderHash: string
    remainingMakerAmount: string
    allowance: string
  }
}

Fields

orderHash · string

Order hash

remainingMakerAmount · string

Remaining amount to fill

allowance · string

Current token allowance for Limit Order Protocol

Example

ws.order.onOrderAllowanceChange((data) => {
  console.log(`Allowance changed for ${data.orderHash}`)
  console.log(`  Allowance: ${data.allowance}`)
  console.log(`  Remaining: ${data.remainingMakerAmount}`)
})

secret_shared

Emitted when a secret is shared with the relayer.

Event Structure

{
  event: 'secret_shared',
  data: {
    idx: number
    secret: string
    srcImmutables: Immutables
    dstImmutables: Immutables
  }
}

Fields

idx · number

Index of the shared secret

secret · string

The revealed secret

srcImmutables · Immutables

Source escrow immutables

dstImmutables · Immutables

Destination escrow immutables

Example

ws.order.onOrderSecretShared((data) => {
  console.log(`Secret ${data.idx} shared`)
  console.log(`  Secret: ${data.secret}`)
})

Subscribing to All Events

ws.order.onOrder((event) => {
  console.log(`Event: ${event.event}`)
  
  switch (event.event) {
    case EventType.OrderCreated:
      // Handle order_created
      break
    case EventType.OrderFilled:
      // Handle order_filled
      break
    case EventType.OrderFilledPartially:
      // Handle order_filled_partially
      break
    case EventType.OrderCancelled:
      // Handle order_cancelled
      break
    case EventType.OrderInvalid:
      // Handle order_invalid
      break
    case EventType.OrderBalanceChange:
      // Handle order_balance_change
      break
    case EventType.OrderAllowanceChange:
      // Handle order_allowance_change
      break
    case EventType.OrderSecretShared:
      // Handle secret_shared
      break
  }
})

Event Filtering

Filter events for specific orders:

const myOrderHash = '0x...'

ws.order.onOrder((event) => {
  if ('orderHash' in event.data && event.data.orderHash === myOrderHash) {
    console.log(`Event for my order:`, event.event)
  }
})

Related

• WebSocketApi - WebSocket API reference
• RPC Methods - RPC methods reference
• Order Tracking - Order monitoring guide