Polymarket Heartbeat (2026): Keep WebSockets and Orders Alive

What is the Polymarket heartbeat?

The word covers two mechanisms that solve different problems. A WebSocket keepalive proves the connection is alive, so the server keeps streaming to it. The order heartbeat proves your trading process is alive, so the exchange can pull your resting orders when it is not. A bot that quotes on Polymarket usually needs both.

How does the Polymarket order heartbeat work?

Polymarket's docs describe it as a way "to cancel resting orders automatically if your trading process stops responding." It arrived with the January 2026 API update and works in three steps:

1. Start. Send {"heartbeat_id": ""} to POST /v1/heartbeats, signed with the L2 headers of the same CLOB API credentials that own the orders you want to protect.
2. Chain. The response carries a heartbeat_id. Five seconds later, send that ID back. Each success returns a new ID for the next call.
3. Recover. If an ID is invalid or expired, the CLOB answers HTTP 400 and includes the ID it expected. Sign a new request with that ID and retry.

The timing is strict: "Once the first heartbeat is accepted, the CLOB expects the account to keep sending them; if a valid heartbeat is not received within 10 seconds, all open orders owned by those CLOB API credentials are canceled." The check runs every five seconds, so cancellation can arrive up to five seconds after the timeout. Sending every 5 seconds, as the docs advise, keeps two attempts inside each 10-second window.

In our checks on 3 October 2026, POST /v1/heartbeats and the unversioned POST /heartbeats both answered HTTP 401 with Unauthorized/Invalid api key when called without credentials, so both routes are live and both need L2 authentication. The API reference still lists /heartbeats, which takes no body and returns {"status": "ok"}. Polymarket's order management guide uses the ID-chained /v1/heartbeats, and so does this post.

How do you send Polymarket heartbeats in code?

Neither unified SDK wraps the order heartbeat yet. The guide's TypeScript and Python tabs read "Content coming soon," and @polymarket/client 0.12.0 has no method for it, so call the endpoint directly. This TypeScript loop needs nothing beyond Node's built-in crypto and fetch:

import { createHmac } from 'node:crypto';

const CLOB = 'https://clob.polymarket.com';
const PATH = '/v1/heartbeats';
const creds = {
  address: process.env.POLY_SIGNER_ADDRESS!,
  key: process.env.POLY_API_KEY!,
  secret: process.env.POLY_API_SECRET!,
  passphrase: process.env.POLY_PASSPHRASE!,
};

function l2Headers(body: string): Record<string, string> {
  const timestamp = String(Math.floor(Date.now() / 1000));
  const signature = createHmac('sha256', Buffer.from(creds.secret, 'base64'))
    .update(timestamp + 'POST' + PATH + body)
    .digest('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_');
  return {
    'Content-Type': 'application/json',
    POLY_ADDRESS: creds.address,
    POLY_API_KEY: creds.key,
    POLY_PASSPHRASE: creds.passphrase,
    POLY_SIGNATURE: signature,
    POLY_TIMESTAMP: timestamp,
  };
}

let heartbeatId = '';

async function sendHeartbeat(retry = true): Promise<void> {
  const body = JSON.stringify({ heartbeat_id: heartbeatId });
  const res = await fetch(CLOB + PATH, { method: 'POST', headers: l2Headers(body), body });
  const data = (await res.json()) as { heartbeat_id?: string };
  if (data.heartbeat_id) heartbeatId = data.heartbeat_id;
  if (res.status === 400 && retry) return sendHeartbeat(false); // stale ID: retry once with the expected one
  if (!res.ok) throw new Error(`Heartbeat failed with HTTP ${res.status}`);
}

await sendHeartbeat();
setInterval(() => {
  sendHeartbeat().catch((err) => console.error(err));
}, 5_000);

What happens when the heartbeat stops?

For the order heartbeat, the answer is documented and blunt: every open order owned by those CLOB API credentials is canceled, 10 to 15 seconds after the last valid heartbeat. Stream updates do not replay what you missed, so after reconnecting, Polymarket's docs say to fetch your open orders and recent trades before acting on new events. Trading involves risk, and the heartbeat only limits how long stale quotes can rest. It does not undo fills that happened before the cancel.

For WebSockets, the result depends on the socket:

PolyBolt pairs its close codes with retry advice. On 4002, reconnect with exponential backoff and jitter, then authenticate again and resend your subscriptions. Sequence numbers start over on the new connection. A 4003 means the server is draining, so reconnect after a random delay of 0 to 10 seconds. In our checks, PolyBolt's protocol pings arrived 25 seconds apart, and an application-level {"op":"ping","rid":"p1"} came back as {"op":"pong","rid":"p1"}.

How do you keep the market and user channels alive?

These two channels use an application-level heartbeat, not WebSocket protocol pings. You send the literal text PING, and the server answers with a bare PONG. This script holds a market channel open and answers the sports socket, using Node's built-in WebSocket client. We ran it on Node 24:

const TOKEN_ID = 'YOUR_TOKEN_ID';

// Market channel: you send PING every 10 seconds and the server answers PONG
const market = new WebSocket('wss://ws-subscriptions-clob.polymarket.com/ws/market');
let pingTimer;

market.addEventListener('open', () => {
  market.send(JSON.stringify({ assets_ids: [TOKEN_ID], type: 'market' }));
  pingTimer = setInterval(() => market.send('PING'), 10_000);
});
market.addEventListener('message', ({ data }) => {
  if (data === 'PONG') return; // heartbeat reply, not JSON
  const event = JSON.parse(data);
  // handle book, price_change, last_trade_price and tick_size_change events
});
market.addEventListener('close', () => clearInterval(pingTimer));

// Sports channel: the server pings you, so answer a text ping with pong
const sports = new WebSocket('wss://sports-api.polymarket.com/ws');
sports.addEventListener('message', ({ data }) => {
  if (data === 'ping') return sports.send('pong');
  const game = JSON.parse(data);
});

One caution on sports. Polymarket's docs say the server sends a text ping every 5 seconds, but in our checks it sent standard WebSocket ping frames every 15 seconds instead, which built-in clients answer automatically. With automatic pongs switched off, the server dropped our connection at 45 seconds, so leave protocol pongs on and keep the text reply too.

Does Polymarket Perps have a dead man's switch?

Yes, and it works differently. Perps auto-cancel is "a dead man's switch for your open orders." You arm it with a deadline at least five seconds in the future, and the exchange cancels every open order on the account when that deadline passes. Keep re-arming it while your process runs. Polymarket's example arms a 60-second deadline and re-arms every 20 seconds. The switch fires once and then clears itself, so orders placed afterwards are unprotected until you arm it again.

Over the API it is PATCH /v1/trade/auto-cancel on api.perpetuals.polymarket.com, with a time of 0 to disarm, and GET /v1/account/auto-cancel reports the deadline and trigger count. The TypeScript SDK wraps it as session.armAutoCancel(), disarmAutoCancel() and fetchAutoCancelStatus(), and the Python SDK uses the snake_case equivalents. An account can trigger it up to 1,000 times per UTC day, so disarm on a clean shutdown instead of letting it fire.

How do you manage connections across venues?

Every venue brings its own sockets, keepalive rules and cancel logic, and a bot that trades beyond Polymarket inherits all of them. The Predictefy API streams order books and trades from 15+ venues over its WebSocket streams, and orders are signed in your own wallet or process, so Predictefy never holds your funds or keys. Paper trading costs 0 credits on every plan, which makes it a good place to rehearse how your bot handles open orders before real ones rest on a book.

Frequently Asked Questions