Subscribe

Subscribe to real-time order data via WebSocket

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

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": ["*"]
    }
}

Condition IDs

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

Market Slugs

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

Next Steps

• Unsubscribe from a subscription
• Update an existing subscription
• Learn about SDKs for easier integration