Subscriptions

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

Field	Required	Description
`action`	Yes	`"subscribe"`
`platform`	Yes	`"polymarket"` (Polymarket channels) or `"chainlink"` (crypto-prices channel)
`version`	Yes	`1`
`type`	Yes	Channel: `"orders"`, `"activity"`, `"lifecycle"`, `"orderbook"`, `"oracle"`, `"collateral"`, or `"crypto"`
`filters`	Yes	Object with exactly one key: `users`, `token_ids`, `condition_ids`, `market_slugs`, or `feeds`. 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.

Value	Behavior	Plan Required
`"confirmed"` (default)	Only confirmed (mined) events	Any plan
`"all"`	Both pending + confirmed events	Dev+
`"pending"`	Only pending (mempool) events	Dev+

Omitting status defaults to "confirmed" - works on all tiers. Free tier subscribing with "all" or "pending" returns PLAN_REQUIRED.

Filter Types

Filter	Description	Example
`users`	Wallet addresses	`["0x123...", "0xabc..."]`
`token_ids`	CLOB token IDs (orderbook only)	`["82855...", "55194..."]`
`condition_ids`	Market condition IDs	`["0x456...", "0x789..."]`
`market_slugs`	Market URL slugs	`["will-donald-trump-win-the-2024-us-presidential-election"]`
`feeds`	Chainlink crypto feed symbols (crypto-prices only)	`["BTC/USD", "ETH/USD"]`

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

Track trades from specific wallet addresses:

{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "orders",
  "filters": {
    "users": [
      "0x1234567890abcdef1234567890abcdef12345678",
      "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
    ]
  }
}

Track splits, merges, and redemptions on a specific market:

{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "activity",
  "filters": {
    "condition_ids": ["0x1234567890abcdef1234567890abcdef12345678901234567890abcdef12345678"]
  }
}

Track token registrations and market resolutions:

{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "lifecycle",
  "filters": {
    "condition_ids": ["0x1234567890abcdef1234567890abcdef12345678901234567890abcdef12345678"]
  }
}

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.

Getting Started

Ticks

Markets

Discovery & Taxonomy

Pricing & Candles

Orderbooks

Trades

Activity & Positions

Wallet Identity

Wallet Positions & P&L

Smart Money & Leaderboards

Oracle & Settlement

Builders

Real-Time Signals (WebSocket)

Backtesting

Reference

Request

Fields

Status Filter (Orders Channel)

Filter Types

Success Response

Examples

Wildcard subscription (Pro only)

Unsubscribe

Request

Response

Update Subscription

Request

Response

​Subscribe

​Request

​Fields

​Status Filter (Orders Channel)

​Filter Types

​Success Response

​Examples

​Subscribe to trade alerts for wallets

​Subscribe to activity for a market

​Subscribe to lifecycle events

​Subscribe to pending + confirmed trades

​Wildcard subscription (Pro only)

​Unsubscribe

​Request

​Response

​Update Subscription

​Request

​Response

Subscribe

Request

Fields

Status Filter (Orders Channel)

Filter Types

Success Response

Examples

Subscribe to trade alerts for wallets

Subscribe to activity for a market

Subscribe to lifecycle events

Subscribe to pending + confirmed trades

Wildcard subscription (Pro only)

Unsubscribe

Request

Response

Update Subscription

Request

Response