Skip to main content

​
Subscribe

Create a subscription to receive real-time events matching your filters.

​
Request

{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "orders",
  "filters": {
    "users": ["0x1234...", "0x5678..."]
  }
}

​
Fields

FieldRequiredDescription
actionYes"subscribe"
platformYes"polymarket"
versionYes1
typeYesChannel: "orders", "activity", "lifecycle", "orderbook", or "oracle"
filtersYesObject with exactly one key: users, token_ids, condition_ids, or market_slugs. Optionally includes status for the orders channel.
Set the filter value to ["*"] to receive all events on that channel (wildcard subscription, Pro plan only).

​
Status Filter (Orders Channel)

The status filter controls whether you receive pending (mempool) events, confirmed (on-chain) events, or both on the orders channel.
ValueBehaviorPlan Required
"confirmed" (default)Only confirmed (mined) eventsAny plan
"all"Both pending + confirmed eventsDev+
"pending"Only pending (mempool) eventsDev+
Omitting status defaults to "confirmed" - fully backward compatible.

​
Filter Types

FilterDescriptionExample
usersWallet addresses["0x123...", "0xabc..."]
token_idsCLOB token IDs (orderbook only)["82855...", "55194..."]
condition_idsMarket condition IDs["0x456...", "0x789..."]
market_slugsMarket URL slugs["will-donald-trump-win-the-2024-us-presidential-election"]
Not all filters are available on all channels. See the filter availability table for details.
The orderbook channel requires exactly one of token_ids, condition_ids, or market_slugs. The users filter is not supported. Update (action: "update") is also not supported. Unsubscribe and resubscribe to change filters.
The oracle channel supports condition_ids and market_slugs. The users and token_ids filters are not supported.

​
Success Response

{
  "type": "ack",
  "subscription_id": "sub_2f4b15b33798",
  "channel": "trades"
}
Save the subscription_id to update or unsubscribe later.

​
Examples

​
Subscribe to trade alerts for wallets

Track trades from specific wallet addresses: 
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "orders",
  "filters": {
    "users": [
      "0x1234567890abcdef1234567890abcdef12345678",
      "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
    ]
  }
}

​
Subscribe to activity for a market

Track splits, merges, and redemptions on a specific market: 
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "activity",
  "filters": {
    "condition_ids": ["0x1234567890abcdef1234567890abcdef12345678901234567890abcdef12345678"]
  }
}

​
Subscribe to lifecycle events

Track token registrations and market resolutions: 
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "lifecycle",
  "filters": {
    "condition_ids": ["0x1234567890abcdef1234567890abcdef12345678901234567890abcdef12345678"]
  }
}

​
Subscribe to pending + confirmed trades

Get early trade signals from the mempool alongside confirmed events: 
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "orders",
  "filters": {
    "users": ["*"],
    "status": "all"
  }
}

​
Wildcard subscription (Pro only)

Subscribe to all trades across Polymarket: 
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "orders",
  "filters": {
    "users": ["*"]
  }
}
A wildcard connection cannot mix wildcard and regular subscriptions on the same channel. Up to 2 wildcard connections per channel per API key.

​
Unsubscribe

Remove an existing subscription using its ID.

​
Request

{
  "action": "unsubscribe",
  "subscription_id": "sub_2f4b15b33798"
}

​
Response

{
  "type": "ack",
  "subscription_id": "sub_2f4b15b33798",
  "channel": "trades"
}

​
Update Subscription

Replace the entire filter set on an existing subscription.

​
Request

{
  "action": "update",
  "subscription_id": "sub_2f4b15b33798",
  "filters": {
    "condition_ids": ["0xabcd..."]
  }
}
You can also update the status filter on an existing orders subscription: 
{
  "action": "update",
  "subscription_id": "sub_2f4b15b33798",
  "filters": {
    "users": ["*"],
    "status": "pending"
  }
}

​
Response

{
  "type": "ack",
  "subscription_id": "sub_2f4b15b33798",
  "channel": "trades"
}
Updating replaces the existing filters entirely. Include all items you want to track.