> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domeapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
    "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:

> [tab] Users
>
> ### Filter by Wallet Addresses
>
> Track orders from specific wallet addresses or use a wildcard to receive all trades.
>
> **Specific Wallet Addresses:**
>
> ```json theme={null}
> {
>     "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:
>
> ```json theme={null}
> {
>     "action": "subscribe",
>     "platform": "polymarket",
>     "version": 1,
>     "type": "orders",
>     "filters": {
>         "users": ["*"]
>     }
> }
> ```

> [tab] 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:**
>
> ```json theme={null}
> {
>     "action": "subscribe",
>     "platform": "polymarket",
>     "version": 1,
>     "type": "orders",
>     "filters": {
>         "condition_ids": [
>             "0x17815081230e3b9c78b098162c33b1ffa68c4ec29c123d3d14989599e0c2e113"
>         ]
>     }
> }
> ```
>
> **Multiple Condition IDs:**
>
> You can track multiple conditions in a single subscription:
>
> ```json theme={null}
> {
>     "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

> [tab] Market Slugs
>
> ### Filter by Market Slugs
>
> Track all trades within specific markets. Market slugs are unique identifiers for each market on Polymarket.
>
> **Single Market:**
>
> ```json theme={null}
> {
>     "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:
>
> ```json theme={null}
> {
>     "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](https://docs.domeapi.io/api-reference/endpoint/get-markets.md) 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:

```json theme={null}
{
    "type": "ack",
    "subscription_id": "sub_gq5c3resmrq"
}
```

**Important:** Save the `subscription_id` - you'll need it to [unsubscribe](https://docs.domeapi.io/websockets/unsubscribe.md) or [update](https://docs.domeapi.io/websockets/update.md) your subscription later.

## Receiving Order Events

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

```json theme={null}
{
    "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](https://docs.domeapi.io/websockets/unsubscribe.md)
* [Update an existing subscription](https://docs.domeapi.io/websockets/update.md)
* Learn about [SDKs](https://docs.domeapi.io/websockets/polymarket-websockets-sdk.md) for easier integration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.