WebSocket Events

Subscribe to real-time order events and RPC responses

The WebSocket API provides comprehensive event subscriptions for monitoring order lifecycle and querying data through RPC methods.

Order Events

Subscribe to order-related events through the order namespace.

Subscribe to All Order Events

Listen to all order events with a single subscription:

import { WebSocketApi } from '@1inch/cross-chain-sdk'

const ws = new WebSocketApi({
  url: 'wss://api.1inch.com/fusion-plus/ws',
  authKey: 'your-auth-key'
})

ws.order.onOrder((data) => {
  if (data.event === 'order_created') {
    console.log('Order created:', data.data.orderHash)
  }
  if (data.event === 'order_invalid') {
    console.log('Order invalid:', data.data.orderHash)
  }
  if (data.event === 'order_filled') {
    console.log('Order filled:', data.data.orderHash)
  }
})

Order Created

Triggered when a new order is created:

ws.order.onOrderCreated((data) => {
  console.log('New order:', {
    orderHash: data.data.orderHash,
    srcChainId: data.data.srcChainId,
    dstChainId: data.data.dstChainId,
    quoteId: data.data.quoteId
  })
})

Event Data Structure:

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

Order Filled

Triggered when an order is completely filled:

ws.order.onOrderFilled((data) => {
  console.log('Order filled:', data.data.orderHash)
})

Event Data Structure:

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

Order Partially Filled

Triggered when an order is partially filled:

ws.order.onOrderFilledPartially((data) => {
  console.log('Partial fill:', {
    orderHash: data.data.orderHash,
    remainingAmount: data.data.remainingMakerAmount
  })
})

Event Data Structure:

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

Order Cancelled

Triggered when an order is cancelled:

ws.order.onOrderCancelled((data) => {
  console.log('Order cancelled:', {
    orderHash: data.data.orderHash,
    remainingAmount: data.data.remainingMakerAmount
  })
})

Event Data Structure:

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

Order Invalid

Triggered when an order becomes invalid:

ws.order.onOrderInvalid((data) => {
  console.log('Order invalid:', data.data.orderHash)
})

Event Data Structure:

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

Order Balance Change

Triggered when the maker’s balance changes affecting the order:

ws.order.onOrderBalanceChange((data) => {
  console.log('Balance changed:', {
    orderHash: data.data.orderHash,
    balance: data.data.balance,
    remainingAmount: data.data.remainingMakerAmount
  })
})

Event Data Structure:

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

Order Allowance Change

Triggered when the maker’s token allowance changes:

ws.order.onOrderAllowanceChange((data) => {
  console.log('Allowance changed:', {
    orderHash: data.data.orderHash,
    allowance: data.data.allowance,
    remainingAmount: data.data.remainingMakerAmount
  })
})

Event Data Structure:

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

Secret Shared

Triggered when a secret is shared for cross-chain order resolution:

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

Event Data Structure:

{
  event: 'secret_shared',
  data: {
    idx: number
    secret: string
    srcImmutables: Jsonify<Immutables<AddressLike>>
    dstImmutables: Jsonify<Immutables<AddressLike>>
  }
}

RPC Methods

The rpc namespace provides request/response methods for querying data.

Ping

Send a health check ping:

ws.rpc.ping()

ws.rpc.onPong((data) => {
  console.log('Pong received:', data)
})

Get Active Orders

Retrieve a list of active orders with pagination:

// Request active orders
ws.rpc.getActiveOrders({ page: 1, limit: 20 })

// Handle response
ws.rpc.onGetActiveOrders((data) => {
  console.log('Active orders:', data.items)
  console.log('Total:', data.meta.totalItems)
})

Response Structure:

{
  items: ActiveOrder[]
  meta: {
    totalItems: number
    itemCount: number
    itemsPerPage: number
    totalPages: number
    currentPage: number
  }
}

Get Secrets

Retrieve resolver secrets with pagination:

ws.rpc.getSecrets({ page: 1, limit: 10 })

ws.rpc.onGetSecrets((data) => {
  if ('error' in data) {
    console.error('Error:', data.error)
  } else {
    console.log('Secrets:', data.secrets)
    console.log('Order type:', data.orderType)
  }
})

Get Allowed Methods

Retrieve the list of available RPC methods:

ws.rpc.getAllowedMethods()

ws.rpc.onGetAllowedMethods((methods) => {
  console.log('Available methods:', methods)
  // ['ping', 'getAllowedMethods', 'getActiveOrders', 'getSecrets']
})

Event Types Reference

OrderEventType

Union type of all order events:

type OrderEventType =
  | OrderCreatedEvent
  | OrderInvalidEvent
  | OrderBalanceChangeEvent
  | OrderAllowanceChangeEvent
  | OrderFilledEvent
  | OrderFilledPartiallyEvent
  | OrderCancelledEvent
  | OrderSecretSharedEvent

EventType Enum

All available event type constants:

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'
}

RpcMethod Enum

All available RPC methods:

enum RpcMethod {
  GetAllowedMethods = 'getAllowedMethods',
  Ping = 'ping',
  GetActiveOrders = 'getActiveOrders',
  GetSecrets = 'getSecrets'
}

Low-Level Events

For advanced use cases, subscribe to low-level WebSocket events:

import { WebSocketEvent } from '@1inch/cross-chain-sdk'

// Connection opened
ws.on(WebSocketEvent.Open, () => {
  console.log('Connected')
})

// Message received
ws.on(WebSocketEvent.Message, (data) => {
  console.log('Raw message:', data)
})

// Connection closed
ws.on(WebSocketEvent.Close, () => {
  console.log('Disconnected')
})

// Error occurred
ws.on(WebSocketEvent.Error, (error) => {
  console.error('WebSocket error:', error)
})

WebSocketEvent Enum

enum WebSocketEvent {
  Close = 'close',
  Error = 'error',
  Message = 'message',
  Open = 'open'
}

Complete Example

Here’s a complete example monitoring all order events:

import { WebSocketApi } from '@1inch/cross-chain-sdk'

const ws = new WebSocketApi({
  url: 'wss://api.1inch.com/fusion-plus/ws',
  authKey: 'your-auth-key'
})

// Connection management
ws.onOpen(() => console.log('Connected to WebSocket'))
ws.onError((error) => console.error('WebSocket error:', error))
ws.onClose(() => console.log('WebSocket closed'))

// Order lifecycle events
ws.order.onOrderCreated((data) => {
  console.log('📝 Order created:', data.data.orderHash)
})

ws.order.onOrderFilled((data) => {
  console.log('✅ Order filled:', data.data.orderHash)
})

ws.order.onOrderFilledPartially((data) => {
  console.log('⏳ Order partially filled:', {
    hash: data.data.orderHash,
    remaining: data.data.remainingMakerAmount
  })
})

ws.order.onOrderCancelled((data) => {
  console.log('❌ Order cancelled:', data.data.orderHash)
})

ws.order.onOrderInvalid((data) => {
  console.log('⚠️ Order invalid:', data.data.orderHash)
})

// State changes
ws.order.onOrderBalanceChange((data) => {
  console.log('💰 Balance changed:', data.data)
})

ws.order.onOrderAllowanceChange((data) => {
  console.log('🔓 Allowance changed:', data.data)
})

// Get active orders on connection
ws.onOpen(() => {
  ws.rpc.getActiveOrders({ limit: 50 })
})

ws.rpc.onGetActiveOrders((orders) => {
  console.log(`Found ${orders.meta.totalItems} active orders`)
})

Next Steps

Setup

Learn how to configure WebSocket connections

Overview

Understand when to use WebSocket vs REST API