Subscribe

Overview

The subscribe action allows you to receive real-time order updates from Polymarket. You can filter orders by different criteria to receive only the data you need.

Subscription Message Format

All subscription messages follow this base format:

{
    "action": "subscribe",
    "platform": "polymarket",
    "version": 1,
    "type": "orders",
    "filters": {
        // Filter options (see below)
    }
}

Required Parameters:

action: Must be "subscribe"
platform: Must be "polymarket"
version: Currently 1
type: Must be "orders"
filters: Object containing filter criteria (see filter types below)

Tier Limits

Subscription limits vary by tier:

Tier	Subscriptions	Wallets per Subscription
Free	2	5
Dev	500	500
Enterprise	Custom	Custom

Filter Types

You can subscribe to orders using one of three filter criteria:

Users
Condition IDs
Market Slugs

Filter by Wallet Addresses

Track orders from specific wallet addresses or use a wildcard to receive all trades.Specific Wallet Addresses:

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

You’ll receive order events when any of the specified wallet addresses execute trades.Wildcard - All Trades:To receive all trades across Polymarket, use a wildcard:

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

Filter by Condition IDs

Track orders for specific market conditions. This is useful when you want to monitor specific outcomes or tokens within markets.Single Condition ID:

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

Multiple Condition IDs:You can track multiple conditions in a single subscription:

{
    "action": "subscribe",
    "platform": "polymarket",
    "version": 1,
    "type": "orders",
    "filters": {
        "condition_ids": [
            "0x17815081230e3b9c78b098162c33b1ffa68c4ec29c123d3d14989599e0c2e113",
            "0x592b8a416cbe36aa7bb40df85a61685ebd54ebbd2d55842f1bb398cae4f40dfc"
        ]
    }
}

You’ll receive order events when trades occur for any of the specified condition IDs.Use Cases:

Monitor specific tokens or outcomes within a market
Track trading activity for particular conditions
Build analytics dashboards for specific market conditions
Create alerts for trades on specific conditions

Filter by Market Slugs

Track all trades within specific markets. Market slugs are unique identifiers for each market on Polymarket.Single Market:

{
    "action": "subscribe",
    "platform": "polymarket",
    "version": 1,
    "type": "orders",
    "filters": {
        "market_slugs": [
            "btc-updown-15m-1762755300"
        ]
    }
}

Multiple Markets:You can track multiple markets in a single subscription:

{
    "action": "subscribe",
    "platform": "polymarket",
    "version": 1,
    "type": "orders",
    "filters": {
        "market_slugs": [
            "btc-updown-15m-1762755300",
            "eth-price-2024-12-31"
        ]
    }
}

You’ll receive order events when trades occur in any of the specified markets.Finding Market Slugs:

In the URL of Polymarket market pages
From the Markets API endpoint response
In order event data from other subscriptions

Use Cases:

Monitor all trading activity within specific markets
Track market-wide order flow
Build market-specific analytics
Create alerts for trades in particular markets

Subscription Acknowledgment

After sending a subscription message, you’ll receive an acknowledgment from the server:

{
    "type": "ack",
    "subscription_id": "sub_gq5c3resmrq"
}

Important: Save the subscription_id - you’ll need it to unsubscribe or update your subscription later.

Receiving Order Events

When orders matching your subscription filters are executed, you’ll receive event messages in real-time:

{
    "type": "event",
    "subscription_id": "sub_gq5c3resmrq",
    "data": {
        "token_id": "80311845198420617303393545005967792170450763818026370381995461841892638500659",
        "token_label": "No",
        "side": "BUY",
        "market_slug": "btc-updown-15m-1762479900",
        "condition_id": "0x5853a47d2d7d97571684c458e2ac28f7f232e12d5490a96cc5b302bd8b4c61bd",
        "shares": 9000000,
        "shares_normalized": 9,
        "price": 0.56,
        "tx_hash": "0xaccc1246d7bc1c95ad44789a6e7ecbc7819dd308632aa0190fedf9673c034077",
        "title": "Bitcoin Up or Down - November 6, 8:45PM-9:00PM ET",
        "timestamp": 1762480391,
        "order_hash": "0xc2b8ee7c9dced1374ac8e2307c65e5204283781c98e1640e28d25d6cc14a0e13",
        "user": "0x6031b6eed1c97e853c6e0f03ad3ce3529351f96d",
        "taker": "0x8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e"
    }
}

Getting started

Polymarket

SDKs

Overview

Subscription Message Format

Tier Limits

Filter Types

Filter by Wallet Addresses

Filter by Condition IDs

Filter by Market Slugs

Subscription Acknowledgment

Receiving Order Events

Next Steps

​Overview

​Subscription Message Format

​Tier Limits

​Filter Types

​Filter by Wallet Addresses

​Filter by Condition IDs

​Filter by Market Slugs

​Subscription Acknowledgment

​Receiving Order Events

​Next Steps

Overview

Subscription Message Format

Tier Limits

Filter Types

Filter by Wallet Addresses

Filter by Condition IDs

Filter by Market Slugs

Subscription Acknowledgment

Receiving Order Events

Next Steps