Skip to Content
API ReferenceREST APIWebSocket Endpoints

WebSocket Endpoints

The Nord API provides WebSocket connections for real-time data streaming.

Base URLs

EnvironmentURL
Mainnetwss://zo-mainnet.n1.xyz
Devnetwss://zo-devnet.n1.xyz

Available Streams

StreamEndpointDescription
Candlescandle@{symbol}:{resolution}OHLCV candlestick data
Tradestrades@{symbol}Real-time trade executions
Orderbookdeltas@{symbol}Orderbook updates (bids/asks)
Accountaccount@{account_id}Account updates (fills, orders, balances)

You can subscribe to multiple streams in a single connection:

wss://{host}/ws/trades@BTCUSD&deltas@BTCUSD&account@42

Candle Data Stream

Stream real-time candlestick (OHLCV) data for charting.

Endpoint

wss://{host}/ws/candle@{symbol}:{resolution}
ParameterTypeDescription
symbolstringTrading pair (e.g., “BTCUSD”)
resolutionstringTimeframe: “1”, “5”, “15”, “30”, “60”, “240”, “1D”, “1W”, “1M”

Message Format

{
  "res": "1",
  "mid": 0,
  "t": 1705312800,
  "o": 97500.0,
  "h": 97550.0,
  "l": 97480.0,
  "c": 97520.0,
  "v": 125.5
}
FieldTypeDescription
resstringResolution/timeframe
midnumberMarket ID
tnumberTimestamp (Unix seconds)
o, h, l, cnumberOpen, High, Low, Close prices
vnumberVolume (optional)

Trades Stream

Stream real-time trade executions for a market.

Endpoint

wss://{host}/ws/trades@{symbol}
ParameterTypeDescription
symbolstringTrading pair (e.g., “BTCUSD”)

Message Format

{
  "trades": {
    "market_symbol": "BTCUSD",
    "trade_id": 12345,
    "price": 97500.0,
    "base_size": 0.5,
    "taker_side": "bid",
    "time": "2024-01-15T10:30:00Z"
  }
}
FieldTypeDescription
market_symbolstringTrading pair symbol
trade_idnumberUnique trade identifier
pricenumberExecution price
base_sizenumberTrade size in base currency
taker_sidestring"bid" (buy) or "ask" (sell)
timestringISO 8601 timestamp

Example: JavaScript

const ws = new WebSocket("wss://zo-mainnet.n1.xyz/ws/trades@BTCUSD");
 
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  const trade = data.trades;
  console.log(`${trade.taker_side.toUpperCase()} ${trade.base_size} @ $${trade.price}`);
};

Orderbook Deltas Stream

Stream real-time orderbook updates (bid/ask changes).

Endpoint

wss://{host}/ws/deltas@{symbol}
ParameterTypeDescription
symbolstringTrading pair (e.g., “BTCUSD”)

Message Format

{
  "delta": {
    "market_symbol": "BTCUSD",
    "update_id": 98765,
    "bids": [[97500.0, 1.5], [97490.0, 2.0]],
    "asks": [[97510.0, 0.8], [97520.0, 1.2]]
  }
}
FieldTypeDescription
market_symbolstringTrading pair symbol
update_idnumberSequence number for ordering
bidsarrayBid updates as [price, size] pairs
asksarrayAsk updates as [price, size] pairs

[!NOTE] A size of 0 indicates the price level should be removed from the orderbook.

Example: JavaScript

const ws = new WebSocket("wss://zo-mainnet.n1.xyz/ws/deltas@BTCUSD");
 
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  const delta = data.delta;
  
  // Apply delta updates to your local orderbook
  delta.bids.forEach(([price, size]) => {
    if (size === 0) {
      // Remove price level
    } else {
      // Update price level with new size
    }
  });
};

Account Stream

Stream real-time account updates including order fills, placements, cancellations, and balance changes.

Endpoint

wss://{host}/ws/account@{account_id}
ParameterTypeDescription
account_idnumberYour Nord account ID

Message Format

{
  "account": {
    "account_id": 42,
    "update_id": 123456,
    "fills": {
      "order_123": {
        "order_id": 123,
        "market_id": 0,
        "maker_id": 42,
        "quantity": 0.5,
        "price": 97500.0
      }
    },
    "places": {
      "order_124": {
        "market_id": 0,
        "side": "bid",
        "price": 97000.0,
        "current_size": 1.0
      }
    },
    "cancels": {},
    "balances": {
      "0": { "token_id": 0, "amount": 1000.0 }
    }
  }
}
FieldTypeDescription
account_idnumberAccount identifier
update_idnumberSequence number for ordering
fillsobjectFilled orders (keyed by order ID)
placesobjectNewly placed orders
cancelsobjectCancelled orders
balancesobjectUpdated token balances

Example: JavaScript

const accountId = 42; // Your account ID
const ws = new WebSocket(`wss://zo-mainnet.n1.xyz/ws/account@${accountId}`);
 
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  const account = data.account;
  
  // Handle fills
  Object.values(account.fills || {}).forEach(fill => {
    console.log(`Order ${fill.order_id} filled: ${fill.quantity} @ $${fill.price}`);
  });
  
  // Handle new orders
  Object.entries(account.places || {}).forEach(([orderId, order]) => {
    console.log(`Order ${orderId} placed: ${order.side} ${order.current_size} @ $${order.price}`);
  });
  
  // Handle cancellations
  Object.keys(account.cancels || {}).forEach(orderId => {
    console.log(`Order ${orderId} cancelled`);
  });
};

Connection Best Practices

  1. Reconnection: Implement automatic reconnection with exponential backoff
  2. Heartbeat: Respond to server pings to keep the connection alive
  3. Sequence tracking: Use update_id to detect missed messages
  4. Resource cleanup: Close connections when no longer needed

Reconnecting Client Example

import asyncio
import websockets
import json
 
async def resilient_stream(symbol: str):
    uri = f"wss://zo-mainnet.n1.xyz/ws/trades@{symbol}"
    retry_delay = 1
    
    while True:
        try:
            async with websockets.connect(uri) as ws:
                retry_delay = 1
                async for message in ws:
                    yield json.loads(message)
        except websockets.ConnectionClosed:
            await asyncio.sleep(retry_delay)
            retry_delay = min(retry_delay * 2, 30)
 
asyncio.run(resilient_stream("BTCUSD"))
Last updated on
GET /timestampInitializing Nord