Livev1.1.2

WebSockets

Stream live prediction-market events over a single persistent connection — no polling, no rate-limit juggling. The first live stream delivers Polymarket trades as they execute, with server-side filtering by wallet, market, outcome, and more so you only receive the events you care about.

Prefer the SDK?

The SDK streaming client (hb.stream.trades()) wraps this protocol — connection, subscription, and reconnection are handled for you. This section documents the raw protocol for building your own client.

Connection

Open a WebSocket connection to the gateway and authenticate with your Heisenberg AI API token as a Bearer credential. Your token is verified at the connection upgrade, so only authenticated clients stream.

WebSocket URL

wss://ripple.heisenberg.so/ws

HTTP Header (sent on the upgrade request)

Authorization: Bearer YOUR_API_TOKEN

Connect from your backend

Stream from a server-side client (Node, Python, Go) and send your token in the Authorization header — the standard setup for production streaming. Keep your API token server-side.

Event Types

Every stream is identified by an event type. Today polymarket.trade is live, the first of more to come. Access to each type is governed by your plan. Call GET /event-types for the catalog you're authorized for — it returns each type's field schema, including a per-field filterable flag that tells you exactly which fields you can filter on.

cURL

curl https://ripple.heisenberg.so/event-types \
  -H "Authorization: Bearer YOUR_API_TOKEN"

200 · Response (abridged)

[
  {
    "name": "polymarket.trade",
    "label": "polymarket_trades_realtime",
    "description": "",
    "schema": {
      "fields": [
        { "name": "slug",         "type": "string", "filterable": true },
        { "name": "proxy_wallet", "type": "string", "filterable": true },
        { "name": "outcome",      "type": "string", "filterable": true },
        { "name": "price",        "type": "float",  "filterable": false }
      ]
    }
  }
]

Abridged — schema.fields lists all 24 fields of polymarket.trade. See Event messages for the full payload.

Next: Subscribe & filters →