Heartbeat & Connection Management

Heartbeat Mechanism

The NBX WebSocket API uses a client-initiated ping/pong heartbeat to keep connections alive. The server does not send pings on its own — it only responds to pings sent by the client.

The connection is dropped by the upstream load balancer after 300 seconds of no traffic in either direction. Any message — a market update from the server, a subscribe from you, a ping, or a pong — resets that idle timer. In practice this means you only need to send a ping during quiet periods; while the server is actively pushing data to you, the connection stays alive on its own.

Recommended pattern

Track the timestamp of the last message you received. If that timestamp is older than some threshold (e.g. 30 seconds), send a ping. This avoids unnecessary pings during active periods and guarantees the connection stays warm during quiet ones.

Client Ping

Send a ping message after a period of no inbound traffic:

{
  "event": "ping"
}

Server Response

The server replies with a pong message:

{
  "event": "pong",
  "data": {
    "message": "pong"
  }
}

The connection is dropped after 300 seconds with no messages flowing in either direction. Any inbound or outbound message resets the idle timer.

Example Implementation

import WebSocket from 'ws';

const IDLE_PING_THRESHOLD_MS = 30_000;
const CHECK_INTERVAL_MS = 10_000;

const ws = new WebSocket('wss://api.novig.us/tape', {
  headers: {
    'Authorization': `Bearer ${ACCESS_TOKEN}`
  }
});

let lastReceivedAt = Date.now();
let idleCheck;

ws.on('open', () => {
  lastReceivedAt = Date.now();
  // Send a ping only if we haven't heard from the server in IDLE_PING_THRESHOLD_MS
  idleCheck = setInterval(() => {
    if (Date.now() - lastReceivedAt >= IDLE_PING_THRESHOLD_MS) {
      ws.send(JSON.stringify({ event: 'ping' }));
    }
  }, CHECK_INTERVAL_MS);
});

ws.on('message', (data) => {
  lastReceivedAt = Date.now();
  const message = JSON.parse(data.toString());

  // Server responds to each client ping with a pong
  if (message.event === 'pong') {
    return;
  }

  // Handle other messages...
});

ws.on('close', () => {
  clearInterval(idleCheck);
});

Introduction

REST Endpoints

Websocket

GraphQL

Heartbeat & Connection Management

Heartbeat Mechanism

Recommended pattern

Client Ping

Server Response

Example Implementation

​Heartbeat Mechanism

​Recommended pattern

​Client Ping

​Server Response

​Example Implementation

Heartbeat Mechanism

Recommended pattern

Client Ping

Server Response

Example Implementation