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", or "lifecycle"
filtersYesObject with exactly one key: users, condition_ids, or market_slugs
Set the filter value to ["*"] to receive all events on that channel (wildcard subscription, Pro plan only).

​
Filter Types

FilterDescriptionExample
usersWallet addresses["0x123...", "0xabc..."]
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.

​
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"]
  }
}

​
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..."]
  }
}

​
Response

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