POST/v1/heartbeats

Send heartbeat (v1)

Sends a heartbeat signal with session tracking via heartbeat ID. The first request should include an empty or initial heartbeat_id. The response will contain a new heartbeat_id that must be used in subsequent requests. If the provided heartbeat_id doesn't match the expected value, the request will fail. If heartbeats are not sent regularly, all open orders for the user will be automatically canceled.

Base URL: https://clob.polymarket.com
Auth: L2 API credentials (key, secret, passphrase)POLY_API_KEY, POLY_ADDRESS, POLY_SIGNATURE, POLY_PASSPHRASE, POLY_TIMESTAMP
Rate limit: 9,000 req / 10s (900 per second)
Limit applies to: CLOB API general

Request body

Field	Type	Required	Description
heartbeat_id	string	yes	The heartbeat ID from the previous response. For the first request, this should be empty or a new UUID. Subsequent requests must use the heartbeat_id returned from the previous response.

Example

curl -X POST "https://clob.polymarket.com/v1/heartbeats" \
  -H "Content-Type: application/json" \
  -H "POLY_API_KEY: $POLY_API_KEY" \
  -H "POLY_ADDRESS: $POLY_ADDRESS" \
  -H "POLY_SIGNATURE: $POLY_SIGNATURE" \
  -H "POLY_PASSPHRASE: $POLY_PASSPHRASE" \
  -H "POLY_TIMESTAMP: $POLY_TIMESTAMP" \
  -d '{
  "heartbeat_id": "<heartbeat_id>"
}'

L2 requests are signed with HMAC-SHA256 using your API secret, and the timestamp is part of the signature, so keep the machine's clock accurate. A missing credential or a stale signature both come back as Unauthorized/Invalid api key. The Python SDK signs for you.

Response fields

Field	Type	Description
heartbeat_id	string	The new heartbeat ID to use in the next request

Responses

Status	Meaning
200	Heartbeat acknowledged with new ID
400	Invalid heartbeat ID - ID doesn't match expected value
401	Unauthorized - Invalid API key or authentication failed
500	Internal server error

Polymarket's API serves current state only, so it cannot show what a market's book looked like after it resolved. PolyTest records Up/Down markets while they run and keeps the snapshots. Try it free, or read the full rate limit reference.

From Polymarket's published OpenAPI spec and rate-limit tables, synced 2026-10-04.