Skip to main content

​
Connection

wss://api.parsecapi.com/ws

​
Authentication

Send an auth message immediately after connecting: 
{ "type": "auth", "api_key": "sk_your_api_key" }
On success: 
{ "type": "auth_ok", "customer_id": "cust_abc123" }
Authentication must complete within 15 seconds or the connection is closed.

​
Subscribing

After authentication, subscribe to markets: 
{
  "type": "subscribe",
  "markets": [
    { "parsec_id": "polymarket:0x1234abcd", "outcome": "yes", "depth": 10 },
    { "parsec_id": "kalshi:KXBTC-25DEC-100K" }
  ]
}
FieldTypeRequiredDescription
parsec_idstringYesMarket identifier ({exchange}:{market_id})
outcomestringNoyes or no (default: yes)
depthnumberNoPrice levels per side, 1–100 (default: 50)

​
Unsubscribing

{
  "type": "unsubscribe",
  "markets": [{ "parsec_id": "polymarket:0x1234abcd", "outcome": "yes" }]
}

​
Resync

Request a fresh snapshot if data becomes stale: 
{ "type": "resync", "parsec_id": "polymarket:0x1234abcd", "outcome": "yes" }

​
Server Messages

​
Orderbook

{
  "type": "orderbook",
  "parsec_id": "polymarket:0x1234abcd",
  "exchange": "polymarket",
  "outcome": "yes",
  "token_id": "217426...",
  "market_id": "0x1234abcd",
  "kind": "snapshot",
  "bids": [[0.65, 1000.0], [0.64, 2500.0]],
  "asks": [[0.66, 800.0], [0.67, 1500.0]],
  "book_state": "fresh",
  "server_seq": 1234,
  "feed_state": "healthy",
  "stale_after_ms": 5000,
  "exchange_ts_ms": 1707044096000,
  "ingest_ts_ms": 1707044096005
}

​
Activity (Trades & Fills)

Trades and fills are sent as type: "activity" with a kind field: 
{
  "type": "activity",
  "parsec_id": "polymarket:0x1234abcd",
  "exchange": "polymarket",
  "outcome": "yes",
  "token_id": "217426...",
  "market_id": "0x1234abcd",
  "kind": "trade",
  "price": 0.65,
  "size": 100.0,
  "trade_id": "trade_123",
  "side": "buy",
  "aggressor_side": "buy",
  "server_seq": 1235,
  "feed_state": "healthy",
  "exchange_ts_ms": 1707044096100,
  "ingest_ts_ms": 1707044096105,
  "source_channel": "trades"
}

{
  "type": "activity",
  "parsec_id": "kalshi:KXBTC-25DEC-100K",
  "exchange": "kalshi",
  "outcome": "yes",
  "token_id": "",
  "market_id": "KXBTC-25DEC-100K",
  "kind": "fill",
  "price": 0.62,
  "size": 50.0,
  "fill_id": "fill_456",
  "order_id": "order_789",
  "side": "buy",
  "server_seq": 1236,
  "feed_state": "healthy",
  "exchange_ts_ms": 1707044096200,
  "ingest_ts_ms": 1707044096205,
  "source_channel": "user"
}

​
Heartbeat

{ "type": "heartbeat", "ts_ms": 1707044096000 }

​
Error

{ "type": "error", "code": 2001, "message": "invalid message" }

​
Resync Required

Sent when you’ve fallen behind on updates: 
{ "type": "resync_required", "parsec_id": "polymarket:0x1234abcd", "outcome": "yes" }

​
Slow Reader

Warning that you’re consuming messages too slowly: 
{ "type": "slow_reader", "parsec_id": "polymarket:0x1234abcd", "outcome": "yes" }

​
Book State

StateDescription
freshData is current and reliable
staleNo recent updates received
needs_refreshSend a Resync message to get fresh data

​
Feed State

StateDescription
healthyConnected and receiving data normally
degradedPartial connectivity or delayed data
disconnectedNo connection to exchange

​
Sequence Numbers

Use server_seq to detect gaps. If you receive a sequence number more than 1 higher than the previous, send a Resync request to recover missed updates.

​
Error Codes

CodeTypeDescription
1001auth_requiredAuthentication required
1002auth_invalidInvalid API key
2001invalid_marketInvalid message format or market ID
2002market_not_foundMarket does not exist
2003exchange_unavailableExchange is unavailable
2005invalid_outcomeInvalid outcome value
3001rate_limitedSubscribe rate limit exceeded
3002max_subscriptionsMax subscriptions reached

​
Limits

  • Max 100 subscriptions per connection
  • Subscribe rate limit: 3 requests per second
  • Authentication timeout: 15 seconds

​
Supported Exchanges

ExchangeOrderbookTradesFills
PolymarketYesYesYes
LimitlessYesYesNo
KalshiYesYesYes
OpinionNoNoNo
Predict.funNoNoNo

​
Example: JavaScript Client

const ws = new WebSocket('wss://api.parsecapi.com/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'auth', api_key: 'sk_your_api_key' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case 'auth_ok':
      console.log('Authenticated:', msg.customer_id);
      ws.send(JSON.stringify({
        type: 'subscribe',
        markets: [{ parsec_id: 'polymarket:0x1234', outcome: 'yes', depth: 10 }]
      }));
      break;

    case 'orderbook':
      console.log(`Orderbook ${msg.parsec_id}:`, msg.bids[0], msg.asks[0]);
      break;

    case 'activity':
      console.log(`${msg.kind} ${msg.parsec_id}: ${msg.size} @ ${msg.price}`);
      break;

    case 'error':
      console.error(`Error ${msg.code}: ${msg.message}`);
      break;

    case 'resync_required':
      ws.send(JSON.stringify({
        type: 'resync',
        parsec_id: msg.parsec_id,
        outcome: msg.outcome
      }));
      break;
  }
};

​
Next Steps

Orderbook Model

Learn about the Orderbook data structure.

WebSocket Usage API

Monitor your WebSocket usage statistics.