Firehose

Every non-empty book for the venues you name, then the live changes. Server-only, on the orderbook socket. Off until Snag enables it for your app (email support@agg.market with your app id), and the handshake requires a valid x-app-api-key; otherwise subscribe is refused with firehose_not_enabled.

Flow per venue: subscribed, one or more orderbook_snapshot_batch slices, firehose_ready, then orderbook_delta_batch (or single orderbook_delta frames for realtime batchMs: 0). A book that first gets levels arrives as a single orderbook_snapshot. Batch entries are the same snapshot and delta objects as the orderbook channel.

Falling behind: over 64 MB of backlog or 30 seconds behind sends firehose_resync, followed by a fresh snapshot. Three in five minutes closes with 4008. A full server refuses subscribe with too_many_connections; reconnect with backoff. See Orderbook firehose.

Send

Subscribe to every non-empty book for selected venues

Requires an app API key on the handshake and firehose enablement for your app. latency follows the orderbook tiers; batchMs applies only to realtime.

FirehoseSubscribe · Subscribe to the orderbook firehose

{
  "action": "subscribe",
  "channel": "firehose",
  "venues": [
    "polymarket"
  ],
  "latency": "realtime",
  "batchMs": 10
}

{  "action": "subscribe",  "channel": "firehose",  "venues": [    "polymarket"  ],  "latency": "realtime",  "batchMs": 10}

Receive

Firehose subscription confirmed

FirehoseSubscribed · Firehose subscription confirmed

{
  "type": "subscribed",
  "channel": "firehose"
}

{  "type": "subscribed",  "channel": "firehose"}

One slice of a venue snapshot

Apply every slice. Do not treat the venue as live until firehose_ready for it. Books in different slices do not depend on each other.

OrderbookSnapshotBatch · Orderbook snapshot batch

{
  "type": "orderbook_snapshot_batch",
  "venue": "polymarket",
  "part": 12,
  "parts": 480,
  "snapshots": [
    {
      "type": "orderbook_snapshot",
      "outcomeId": "vmo_1",
      "seq": 1710000001,
      "checksum": 2918476531,
      "bids": [
        [
          0.55,
          800,
          {
            "polymarket": 800
          }
        ]
      ],
      "asks": [
        [
          0.56,
          600,
          {
            "polymarket": 600
          }
        ]
      ],
      "venueOrderbooks": {
        "polymarket": {
          "bids": [
            [
              0.55,
              800
            ]
          ],
          "asks": [
            [
              0.56,
              600
            ]
          ]
        }
      },
      "venues": {
        "polymarket": {
          "bestBid": 0.55,
          "bestAsk": 0.56
        }
      },
      "midpoint": 0.555,
      "spread": 0.01,
      "timestamp": 1710000000000
    }
  ]
}

{  "type": "orderbook_snapshot_batch",  "venue": "polymarket",  "part": 12,  "parts": 480,  "snapshots": [    {      "type": "orderbook_snapshot",      "outcomeId": "vmo_1",      "seq": 1710000001,      "checksum": 2918476531,      "bids": [        [          0.55,          800,          {            "polymarket": 800          }        ]      ],      "asks": [        [          0.56,          600,          {            "polymarket": 600          }        ]      ],      "venueOrderbooks": {        "polymarket": {          "bids": [            [              0.55,              800            ]          ],          "asks": [            [              0.56,              600            ]          ]        }      },      "venues": {        "polymarket": {          "bestBid": 0.55,          "bestAsk": 0.56        }      },      "midpoint": 0.555,      "spread": 0.01,      "timestamp": 1710000000000    }  ]}

A venue's snapshot has been sent; live deltas follow

FirehoseReady · Firehose venue ready

{
  "type": "firehose_ready",
  "venue": "polymarket"
}

{  "type": "firehose_ready",  "venue": "polymarket"}

Live changes across the venues you stream

Sent per 100 ms flush on the conflated tier, or per batchMs window on realtime. With realtime batchMs: 0, each orderbook_delta is sent on its own instead.

OrderbookDeltaBatch · Orderbook delta batch

{
  "type": "orderbook_delta_batch",
  "deltas": [
    {
      "type": "orderbook_delta",
      "outcomeId": "vmo_1",
      "seq": 1710000002,
      "checksum": 3847261950,
      "bidChanges": [
        [
          0.55,
          900,
          {
            "polymarket": 900
          }
        ]
      ],
      "askChanges": [],
      "venueDeltaBooks": {
        "polymarket": {
          "bidChanges": [
            [
              0.55,
              900
            ]
          ],
          "askChanges": []
        }
      },
      "venues": {
        "polymarket": {
          "bestBid": 0.55,
          "bestAsk": 0.56
        }
      },
      "midpoint": 0.555,
      "spread": 0.01,
      "timestamp": 1710000001000
    }
  ]
}

{  "type": "orderbook_delta_batch",  "deltas": [    {      "type": "orderbook_delta",      "outcomeId": "vmo_1",      "seq": 1710000002,      "checksum": 3847261950,      "bidChanges": [        [          0.55,          900,          {            "polymarket": 900          }        ]      ],      "askChanges": [],      "venueDeltaBooks": {        "polymarket": {          "bidChanges": [            [              0.55,              900            ]          ],          "askChanges": []        }      },      "venues": {        "polymarket": {          "bestBid": 0.55,          "bestAsk": 0.56        }      },      "midpoint": 0.555,      "spread": 0.01,      "timestamp": 1710000001000    }  ]}

OrderbookDelta · Orderbook delta

{
  "type": "orderbook_delta",
  "outcomeId": "clv2abc123def456",
  "channel": "orderbook",
  "seq": 1710000001,
  "checksum": 2918476531,
  "bidChanges": [
    {
      "price": 0.55,
      "totalSize": 1500,
      "venues": {}
    }
  ],
  "askChanges": [
    {
      "price": 0.55,
      "totalSize": 1500,
      "venues": {}
    }
  ],
  "venueDeltaBooks": {},
  "venues": {},
  "midpoint": 0.55,
  "spread": 0.01,
  "tick": 0,
  "markSource": "local",
  "timestamp": 1710000000000
}

{  "type": "orderbook_delta",  "outcomeId": "clv2abc123def456",  "channel": "orderbook",  "seq": 1710000001,  "checksum": 2918476531,  "bidChanges": [    {      "price": 0.55,      "totalSize": 1500,      "venues": {}    }  ],  "askChanges": [    {      "price": 0.55,      "totalSize": 1500,      "venues": {}    }  ],  "venueDeltaBooks": {},  "venues": {},  "midpoint": 0.55,  "spread": 0.01,  "tick": 0,  "markSource": "local",  "timestamp": 1710000000000}

A single snapshot for a book that first gets levels

OrderbookSnapshot · Orderbook snapshot

{
  "type": "orderbook_snapshot",
  "outcomeId": "clv2abc123def456",
  "channel": "orderbook",
  "seq": 1710000001,
  "checksum": 2918476531,
  "bids": [
    {
      "price": 0.55,
      "totalSize": 1500,
      "venues": {}
    }
  ],
  "asks": [
    {
      "price": 0.55,
      "totalSize": 1500,
      "venues": {}
    }
  ],
  "venueOrderbooks": {},
  "venues": {},
  "midpoint": 0.55,
  "spread": 0.01,
  "timestamp": 1710000000000,
  "tick": 0,
  "markSource": "local"
}

{  "type": "orderbook_snapshot",  "outcomeId": "clv2abc123def456",  "channel": "orderbook",  "seq": 1710000001,  "checksum": 2918476531,  "bids": [    {      "price": 0.55,      "totalSize": 1500,      "venues": {}    }  ],  "asks": [    {      "price": 0.55,      "totalSize": 1500,      "venues": {}    }  ],  "venueOrderbooks": {},  "venues": {},  "midpoint": 0.55,  "spread": 0.01,  "timestamp": 1710000000000,  "tick": 0,  "markSource": "local"}

Firehose refusals and resyncs

firehose_not_enabled: the firehose is off for your app or the socket has no valid API key. too_many_connections: the server's firehose capacity is full; close and reconnect with backoff. firehose_resync: you fell behind or the upstream feed was replaced; a fresh snapshot follows.

FirehoseError · Firehose error

{
  "type": "error",
  "code": "firehose_not_enabled"
}

{  "type": "error",  "code": "firehose_not_enabled"}