Skip to main content
Learn how to set up WebSocket connections for real-time order monitoring with the 1inch Cross Chain SDK.

​
Basic Setup

Create a WebSocket instance using the constructor: 
import { WebSocketApi } from '@1inch/cross-chain-sdk'

const ws = new WebSocketApi({
  url: 'wss://api.1inch.com/fusion-plus/ws',
  authKey: 'your-auth-key'
})
The WebSocket automatically connects to the server using version v1.2 of the API.

​
Alternative Creation Methods

​
Using the Static new Method

You can also create instances using the static new method: 
import { WebSocketApi } from '@1inch/cross-chain-sdk'

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

​
Lazy Initialization

By default, WebSocketApi automatically opens a connection when instantiated. For scenarios where you need to defer the connection, use lazy initialization: 
import { WebSocketApi, NetworkEnum } from '@1inch/cross-chain-sdk'

const ws = new WebSocketApi({
  url: 'wss://api.1inch.com/fusion-plus/ws',
  network: NetworkEnum.ETHEREUM,
  lazyInit: true
})

// Connect when ready
ws.init()
Lazy initialization is useful when you need to create the WebSocket instance early but delay the actual connection until a specific event or user action.

​
Custom Provider Implementation

You can provide a custom WebSocket provider instead of using the default ws library: 
import { WsProviderConnector, WebSocketApi } from '@1inch/cross-chain-sdk'

class MyFancyProvider implements WsProviderConnector {
  // Implement required methods:
  // - init(): void
  // - send<T>(message: T): void
  // - on(event: string, cb: Function): void
  // - off(event: string, cb: Function): void
  // - onOpen(cb: Function): void
  // - onMessage(cb: Function): void
  // - onClose(cb: Function): void
  // - onError(cb: Function): void
  // - close(): void
}

const url = 'wss://api.1inch.com/fusion-plus/ws/v1.2'
const provider = new MyFancyProvider({ url })

const wsSdk = new WebSocketApi(provider)
When using a custom provider, ensure you include the full URL path with the version (e.g., /v1.2). The automatic version appending only works with the config-based constructor.

​
Connection Management

​
Opening Connections

Subscribe to the open event to know when the connection is established: 
ws.onOpen(() => {
  console.log('WebSocket connection established')
})

​
Closing Connections

Gracefully close the WebSocket connection: 
ws.close()
Subscribe to close events: 
ws.onClose(() => {
  console.log('WebSocket connection closed')
})

​
Error Handling

Handle connection errors: 
ws.onError((error) => {
  console.error('WebSocket error:', error)
})

​
Configuration Options

​
url
string
required
WebSocket server URL (e.g., wss://api.1inch.com/fusion-plus/ws)
​
authKey
string
Authentication key for the WebSocket connection
​
network
NetworkEnum
Target blockchain network
​
lazyInit
boolean
default:"false"
If true, delays connection until init() is called

​
Low-Level Event Handling

For advanced use cases, you can subscribe to low-level WebSocket events: 
import { WebSocketEvent } from '@1inch/cross-chain-sdk'

ws.on(WebSocketEvent.Error, console.error)

ws.on(WebSocketEvent.Open, function open() {
  ws.send('custom message')
})

ws.on(WebSocketEvent.Message, function message(data) {
  console.log('received: %s', data)
})
Unsubscribe from events: 
function messageHandler(data) {
  console.log('received: %s', data)
}

ws.on(WebSocketEvent.Message, messageHandler)
ws.off(WebSocketEvent.Message, messageHandler)

​
Sending Messages

Send custom messages through the WebSocket: 
ws.send({ type: 'custom', payload: { /* your data */ } })
Messages are automatically serialized with JSON.stringify before sending.

​
Next Steps

Events

Explore available WebSocket events and subscriptions

Overview

Understand the WebSocket API architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us