WebSocket Overview

Connection

Mainnet: wss://api.notional.xyz/ws
Testnet: wss://api.notional-testnet.xyz/ws

Client messages must be JSON text no larger than 16 KiB. Binary messages are not supported.

Protocol

The WebSocket sends live updates. It does not store a complete history that clients can replay. It supports exactly three client methods:

subscribe
unsubscribe
ping

The server returns messages for subscribed channels, subscriptionResponse, pong, or error.

Notional does not accept Hyperliquid’s {"method":"post"} WebSocket messages. Send reads through the HTTP read APIs, including POST /info, and signed actions through POST /exchange. A WebSocket message with method: "post" returns an Unknown method: post error.

{
  "method": "subscribe",
  "subscription": {
    "type": "userFills",
    "user": "0x1111111111111111111111111111111111111111"
  }
}

The type field chooses the subscription. This page calls each subscription type a topic:

User-scoped topics require the actual user address, not an approved API-wallet address.
activeAssetData additionally requires coin.
Global topics omit user.

A successful subscription returns this confirmation:

{
  "channel": "subscriptionResponse",
  "data": {
    "method": "subscribe",
    "subscription": {
      "type": "userFills",
      "user": "0x1111111111111111111111111111111111111111"
    }
  }
}

This message only confirms the subscription. It does not contain current account or market data and does not guarantee that the topic’s first data message was loaded successfully.

Unsubscribe

Send the same subscription fields used to subscribe:

{
  "method": "unsubscribe",
  "subscription": {
    "type": "userFills",
    "user": "0x1111111111111111111111111111111111111111"
  }
}

The server converts user addresses to lowercase and market symbols to uppercase when identifying a subscription. Unsubscribing removes only that subscription and returns a subscriptionResponse with data.method: "unsubscribe".

First Message After Subscribing

A snapshot is a point-in-time copy of the topic’s current data. Not every topic sends one:

Topic	What follows the confirmation
`activeAssetData`	Snapshot with `isSnapshot: true`; failures return `error`
`twapUpdates`	Active TWAP snapshot with `isSnapshot: true`
`notionalMeta`	Metadata snapshot with `isSnapshot: true`
`accountSummary`	Current account data when available; no snapshot flag
`orderUpdates`	Snapshot with `isSnapshot: true`, including `orders: []` when empty
`userFills`, `userOrderRejections`	New messages only; no history is sent when subscribing
`userTransactions`	New messages only; no history is sent when subscribing
`newBlocks`, `newTransactions`	New messages only; no history is sent when subscribing

Do not treat silence after the confirmation as an empty result: a snapshot read can fail after the subscription is acknowledged. Use the corresponding HTTP endpoint to recover current data. The order snapshot also retains terminal Polymarket orders with provisional matched fills until their settlement completes.

Available Topics

Topics for one user

Global topics

Global topics are subscriptions without a user field.

Global Subscription Messages

New Blocks

Subscribe:

{
  "method": "subscribe",
  "subscription": {
    "type": "newBlocks"
  }
}

Update:

{
  "channel": "newBlocks",
  "data": {
    "blockNumber": 12345,
    "timestamp": 1701234567890,
    "transactionCount": 3,
    "blockHash": "0x1234..."
  }
}

New Transactions

Subscribe:

{
  "method": "subscribe",
  "subscription": {
    "type": "newTransactions"
  }
}

Update:

{
  "channel": "newTransactions",
  "data": {
    "transactionId": "0x1234...",
    "type": "OrderPlaced",
    "timestamp": 1701234567890,
    "blockNumber": 12345,
    "txIndex": 0,
    "orderId": "0x5678...",
    "data": {}
  }
}

Connection Management

Notional measures idle time from messages received from the client. Updates sent by the server do not keep an otherwise silent connection alive. Send a JSON ping about every 30 seconds:

{
  "method": "ping"
}

The server responds:

{
  "channel": "pong"
}

A connection with no client activity for 60 seconds is eligible to close with code 1000 and reason Idle timeout.

After a Disconnect

Subscriptions apply only to the current socket and disappear when it closes. The WebSocket cannot replay every missed message. After reconnecting:

Recreate every required subscription.
Call the corresponding HTTP endpoint to check the current data.
Match later WebSocket messages using the order ID, transaction ID, or other field documented by that topic.

A subscription confirmation or first data message does not recover every update missed while the socket was disconnected.

Errors

Protocol and request errors use this format:

{
  "channel": "error",
  "data": {
    "message": "Invalid message format"
  }
}

See Error Responses for shared HTTP retry guidance.

Start Here

Info

Analytics

Exchange

WebSocket

Connection

Protocol

Unsubscribe

First Message After Subscribing

Available Topics

Topics for one user

Global topics

Global Subscription Messages

New Blocks

New Transactions

Connection Management

After a Disconnect

Errors

​Connection

​Protocol

​Subscribe

​Unsubscribe

​First Message After Subscribing

​Available Topics

​Topics for one user

​Global topics

​Global Subscription Messages

​New Blocks

​New Transactions

​Connection Management

​After a Disconnect

​Errors

Connection

Protocol

Subscribe

Unsubscribe

First Message After Subscribing

Available Topics

Topics for one user

Global topics

Global Subscription Messages

New Blocks

New Transactions

Connection Management

After a Disconnect

Errors