Subscriptions & Filters

Subscription types, filter options, and how event matching works.

Subscribe message

Send a JSON message after connecting to start receiving events:

{
  "action": "subscribe",
  "type": "settlements",
  "filters": {
    "wallets": ["0x1234..."],
    "tokens": ["21742633..."],
    "slugs": ["bitcoin-100k-2026"],
    "condition_ids": ["0xabc..."],
    "side": "BUY",
    "status": "pending",
    "min_size": 100,
    "max_size": 10000,
    "event_types": ["settlement", "status_update"],
    "snapshot_count": 50
  }
}

All fields except action are optional.

Subscription types

The type field selects a preset of event types. If you also set filters.event_types, it overrides the preset.

settlements · default

Events: settlement, status_update

Pending and confirmed Polymarket settlements. The default subscription type.

trades · string

Events: settlement, trade, status_update

All trade activity including confirmed on-chain trades.

prices · string

Events: settlement, trade

Price-moving events only. Useful for building price feeds.

blocks · string

Events: block

New Polygon block notifications with Polymarket-specific stats (settlement count, trade volume).

wallets · string

Events: settlement, trade, position_change, deposit, status_update, position_split, position_merge

All activity for specific wallets. Best used with the wallets filter.

markets · string

Events: settlement, trade, position_change, status_update, position_split, position_merge

All activity for specific markets. Best used with tokens, slugs, or condition_ids filters.

large_trades · string

Events: settlement, trade

Whale alerts. Defaults to min_size: 1000 ($1K+) unless you set your own.

global · string

Events: all except position_split and position_merge

Unfiltered stream of every event (firehose), including oracle events. High throughput — use with caution. This counts toward your plan’s firehose connection limit. To include position_split/position_merge, add them explicitly via the event_types filter override.

Firehose refers to any WebSocket subscription with no filters applied — receiving every event at full throughput. Filtered subscriptions (specifying wallets, tokens, slugs, or size thresholds) don’t count toward your firehose limit and use far less bandwidth.

oracle · string

Events: oracle

UMA Optimistic Oracle events: market resolutions, proposals, disputes, flags, and admin actions. See Oracle Event.

chainlink · string

Events: price_feed

Real-time Chainlink Data Streams prices (~1/second). Use the feeds filter to select specific feeds (e.g. ["BTC/USD"]). See Price Feed Event.

Filters

All filters are optional. Omit the filters object entirely to receive all events matching the subscription type.

Market identification

tokens · string[]

Filter by Polymarket conditional token IDs. Match if any token in the list appears in the event.

"tokens": ["21742633143463906290569404...", "98765432..."]

slugs · string[]

Filter by market URL slugs. Resolved to token IDs at subscribe time — zero performance cost after that.

"slugs": ["bitcoin-100k-2026", "trump-2024"]

If a slug isn’t found in metadata, you’ll get a warning in the subscribed response. The subscription still activates for any resolved slugs.

condition_ids · string[]

Filter by Polymarket condition IDs. Resolved to token IDs at subscribe time.

"condition_ids": ["0x123abc..."]

Wallet filtering

wallets · string[]

Filter by wallet addresses (case-insensitive). Matches if the wallet is involved as maker or taker.

"wallets": ["0xabcdef1234567890..."]

Trade filtering

side · string

Filter by trade side. Case-insensitive.

Values: "BUY" or "SELL"

min_size · number

Minimum trade size in USD. Events below this size are dropped.

"min_size": 1000

max_size · number

Maximum trade size in USD. Events above this size are dropped.

status · string · default: "all"

Filter by settlement status.

Value	Description
"pending"	Only pre-chain detections
"confirmed"	Only confirmed in a block
"all"	Both pending and confirmed (default)

Event control

event_types · string[]

Override the subscription type’s default event list. Valid values: "settlement", "trade", "status_update", "block", "position_change", "deposit", "position_split", "position_merge"

snapshot_count · number · default: "20"

Number of recent matching events to receive immediately after subscribing. Max: 200.

Price feed filtering

feeds · string[]

Filter by price feed names. Only applies to chainlink subscriptions.

"feeds": ["BTC/USD"]

Omit to receive all available feeds.

Matching logic

Filters use AND logic between different filter types and OR logic within each filter:

• An event must match all active filter categories (wallets AND tokens AND side AND size range)
• Within a category, matching any value is sufficient (wallet A OR wallet B)
• Empty/omitted filters match everything in that category

Multiple subscriptions

You can send multiple subscribe messages on the same connection — they stack. Each subscribe creates an independent subscription with its own filters. Events matching any of your active subscriptions are delivered, deduplicated so you never receive the same event twice.

// Subscribe to two different wallet groups independently
ws.send(JSON.stringify({
  action: "subscribe",
  type: "wallets",
  filters: { wallets: ["0xaaa..."] }
}));

ws.send(JSON.stringify({
  action: "subscribe",
  type: "wallets",
  filters: { wallets: ["0xbbb..."] }
}));
// Both subscriptions are active — events for either wallet are delivered

Subscribe response

After subscribing, you receive two messages:

1. Snapshot — recent events matching your filters:

{
  "type": "snapshot",
  "count": 20,
  "events": [...]
}

2. Confirmation — your subscription ID and any warnings:

{
  "type": "subscribed",
  "subscriber_id": "550e8400-e29b-41d4-a716-446655440000",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000:1",
  "subscription_type": "settlements",
  "warnings": []
}

Save the subscription_id if you need to remove a specific subscription later.

Unsubscribe

Remove a specific subscription

{"action": "unsubscribe", "subscription_id": "550e8400-...:1"}

Response:

{
  "type": "unsubscribed",
  "subscriber_id": "550e8400-...",
  "subscription_id": "550e8400-...:1"
}

Remove all subscriptions

{"action": "unsubscribe"}

Response:

{"type": "unsubscribed", "subscriber_id": "550e8400-..."}

To change filters on an existing subscription, unsubscribe by subscription_id and send a new subscribe with the updated filters.