WebSockets

Subscribe & filters

Open one or many streams in a single frame, and filter server-side so you only receive the events you care about.

Once connected, send a subscribe frame. Each frame can open multiple subscriptions at once — pass one entry per stream in the subscriptions array. Omit filters (or pass {}) to receive every event of that type.

Subscribe to all trades

JSON · client → server

{
  "action": "subscribe",
  "subscriptions": [
    { "type": "polymarket.trade", "filters": {} }
  ]
}

Subscribe to one market

JSON · client → server

{
  "action": "subscribe",
  "subscriptions": [
    {
      "type": "polymarket.trade",
      "filters": { "slug": "sol-updown-15m-1779670800" }
    }
  ]
}

The server replies with a subscribed acknowledgement listing the event types it granted and a unique id for each subscription. Keep each id — you need it to unsubscribe. The filters you sent are echoed back when present.

JSON · server → client

{
  "action": "subscribed",
  "types": ["polymarket.trade"],
  "subscriptions": [
    {
      "id": "cede7755-c0a6-41b8-b316-ca4377dedb5d",
      "type": "polymarket.trade",
      "filters": { "slug": "sol-updown-15m-1779670800" }
    }
  ]
}

Control messages vs. events

Acknowledgements, errors, and notices carry an action field (subscribed, error, rate_limit, …). Data events instead carry a type and a data object. Branch on whichever field is present. Mixed frames are handled gracefully — the acknowledgement grants every type your plan includes, so the rest of the subscription always goes through.

Filters

Filters are matched server-side with exact equality against the event's top-level data fields, before delivery — so you receive only the events you want. For polymarket.trade, the filterable fields are:

proxy_walletslugcondition_idevent_slugoutcomeoutcome_indexsideassetmakertakertransaction_hashorder_hash

These are the fields you can filter on — GET /event-types is the authoritative source. To track several wallets or markets independently, open one subscription per target in the same subscribe frame.

Build a subscription

Pick your filters and copy the generated subscribe frame — or a ready-to-run Node or Python client — straight into your app.

FiltersNo filters — all trades

{
  "action": "subscribe",
  "subscriptions": [
    {
      "type": "polymarket.trade",
      "filters": {}
    }
  ]
}

Next: Messages & lifecycle →