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

# Subscriptions

> Create and manage WebSocket subscriptions

## Subscribe

Create a subscription to receive real-time events matching your filters.

### Request

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

<Note>
  Not all filters are available on all channels. See the [filter availability table](/websocket/overview#filter-availability-by-channel) for details.
</Note>

<Note>
  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.
</Note>

<Note>
  The **oracle** channel supports `condition_ids` and `market_slugs`. The `users` and `token_ids` filters are not supported.
</Note>

### Success Response

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

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

```json theme={null}
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "activity",
  "filters": {
    "condition_ids": ["0x1234567890abcdef1234567890abcdef12345678901234567890abcdef12345678"]
  }
}
```

### Subscribe to lifecycle events

Track token registrations and market resolutions:

```json theme={null}
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "lifecycle",
  "filters": {
    "condition_ids": ["0x1234567890abcdef1234567890abcdef12345678901234567890abcdef12345678"]
  }
}
```

### Subscribe to pending + confirmed trades

Get early trade signals from the mempool alongside confirmed events:

```json theme={null}
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "orders",
  "filters": {
    "users": ["*"],
    "status": "all"
  }
}
```

### Wildcard subscription (Pro only)

Subscribe to **all** trades across Polymarket:

```json theme={null}
{
  "action": "subscribe",
  "platform": "polymarket",
  "version": 1,
  "type": "orders",
  "filters": {
    "users": ["*"]
  }
}
```

<Warning>
  A wildcard connection cannot mix wildcard and regular subscriptions on the same channel. Up to 2 wildcard connections per channel per API key.
</Warning>

***

## Unsubscribe

Remove an existing subscription using its ID.

### Request

```json theme={null}
{
  "action": "unsubscribe",
  "subscription_id": "sub_2f4b15b33798"
}
```

### Response

```json theme={null}
{
  "type": "ack",
  "subscription_id": "sub_2f4b15b33798",
  "channel": "trades"
}
```

***

## Update Subscription

Replace the entire filter set on an existing subscription.

### Request

```json theme={null}
{
  "action": "update",
  "subscription_id": "sub_2f4b15b33798",
  "filters": {
    "condition_ids": ["0xabcd..."]
  }
}
```

You can also update the `status` filter on an existing orders subscription:

```json theme={null}
{
  "action": "update",
  "subscription_id": "sub_2f4b15b33798",
  "filters": {
    "users": ["*"],
    "status": "pending"
  }
}
```

### Response

```json theme={null}
{
  "type": "ack",
  "subscription_id": "sub_2f4b15b33798",
  "channel": "trades"
}
```

<Note>
  Updating replaces the existing filters entirely. Include all items you want to track.
</Note>