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

# Overview

> Real-time Polymarket trade, activity, and lifecycle events via WebSocket

Real-time streaming of Polymarket on-chain events including trades, position activity, market lifecycle, orderbook updates, and oracle events.

<Note>
  WebSocket requires a **Dev plan or higher** (\$49/mo). [Get your API key →](https://dashboard.predexon.com)
</Note>

***

## Use Cases

<CardGroup cols={2}>
  <Card title="Copytrading" icon="users">
    Subscribe to top traders' wallets and mirror their positions in real time.
  </Card>

  <Card title="Market Monitoring" icon="chart-line">
    Track specific markets for price movements and trading activity.
  </Card>

  <Card title="Portfolio Alerts" icon="bell">
    Monitor wallets for trade confirmations, splits, merges, and redemptions.
  </Card>

  <Card title="Analytics & Research" icon="magnifying-glass-chart">
    Stream all events with wildcard subscriptions to build datasets.
  </Card>

  <Card title="Market Making" icon="scale-balanced">
    Subscribe to real-time depth and price level changes via the orderbook channel.
  </Card>

  <Card title="Mempool Trading" icon="clock">
    Detect trades 3–5 seconds early with pending trade events from the Polygon mempool.
  </Card>
</CardGroup>

***

## Quick Start

```javascript theme={null}
const ws = new WebSocket('wss://wss.predexon.com/v1/your_api_key'); // [!code highlight]

ws.onopen = () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    platform: 'polymarket',
    version: 1,
    type: 'orders', // [!code highlight]
    filters: { users: ['0x1234...'] }
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'event') {
    console.log('Trade:', msg.data);
  }
};
```

***

## Connection

**Endpoint:**

```
wss://wss.predexon.com/v1/YOUR_API_KEY
```

On success:

```json theme={null}
{ "type": "connected", "message": "Connected to Predexon WebSocket" }
```

| HTTP Status | Reason                                |
| ----------- | ------------------------------------- |
| 401         | Missing or invalid API key            |
| 403         | WebSocket requires Dev plan or higher |
| 429         | Connection limit exceeded             |
| 503         | Server at capacity                    |

***

## Channels

| Channel           | Platform     | `type` value   | Description                                                                                                 |
| ----------------- | ------------ | -------------- | ----------------------------------------------------------------------------------------------------------- |
| **Trades**        | `polymarket` | `"orders"`     | Order fills and fee refunds (V1 + V2). Supports [pending events](/websocket/pending-trades).                |
| **Activity**      | `polymarket` | `"activity"`   | Position splits, merges, redemptions, and NegRisk conversions                                               |
| **Lifecycle**     | `polymarket` | `"lifecycle"`  | New market creation (`condition_prepared`), token registration (V1), and resolution                         |
| **Orderbook**     | `polymarket` | `"orderbook"`  | Real-time L2: price changes, trades, book snapshots                                                         |
| **Oracle**        | `polymarket` | `"oracle"`     | UMA events: proposals, disputes, settlements, resets                                                        |
| **Collateral**    | `polymarket` | `"collateral"` | pUSD wrap/unwrap events (V2 deposits and withdrawals)                                                       |
| **Crypto Prices** | `chainlink`  | `"crypto"`     | [Chainlink Data Streams](/websocket/crypto-prices) crypto price ticks (BTC, ETH, SOL, XRP, BNB, DOGE, HYPE) |

### Filter Availability

| Filter           | Trades | Activity | Lifecycle | Orderbook | Oracle | Collateral | Crypto Prices |
| ---------------- | :----: | :------: | :-------: | :-------: | :----: | :--------: | :-----------: |
| `users`          |   Yes  |    Yes   |     -     |     -     |    -   |     Yes    |       -       |
| `token_ids`      |    -   |     -    |     -     |    Yes    |    -   |      -     |       -       |
| `condition_ids`  |   Yes  |    Yes   |    Yes    |    Yes    |   Yes  |      -     |       -       |
| `market_slugs`   |   Yes  |     -    |     -     |    Yes    |   Yes  |      -     |       -       |
| `feeds`          |    -   |     -    |     -     |     -     |    -   |      -     |      Yes      |
| Wildcard `["*"]` |   Yes  |    Yes   |    Yes    |    Yes    |   Yes  |     Yes    |      Yes      |

### Timestamp Units

| Channel    | Unit                                 |
| ---------- | ------------------------------------ |
| Orderbook  | **milliseconds** (Polymarket server) |
| All others | **seconds** (Predexon normalizer)    |

***

## Plan Limits

| Limit                      | Dev | Pro           | Enterprise |
| -------------------------- | --- | ------------- | ---------- |
| Subscriptions / connection | 10  | 100           | Custom     |
| Items / subscription       | 10  | 500           | Custom     |
| Total items                | 100 | 50,000        | Custom     |
| Wildcard subscriptions     | -   | 2 per channel | Custom     |
| Priority routing           | -   | -             | Yes        |

Limits are global across all channels. Wildcard connections are tracked per-channel.

<Warning>
  A wildcard connection cannot mix wildcard and regular subscriptions on the same channel.
</Warning>

***

## Keepalive & Connection Management

<Accordion title="Keepalive details">
  * Server sends a **ping every 30 seconds**; pong required within 60 seconds
  * Idle connections (zero subscriptions) closed after **2 minutes** (close code `4000`)
  * Buffer limits: events dropped at **1 MB**, connection terminated at **4 MB**
</Accordion>

***

## Error Handling

```json theme={null}
{ "type": "error", "code": "ERROR_CODE", "message": "Human-readable message" }
```

<Expandable title="Error codes">
  | Code                        | Description                             |
  | --------------------------- | --------------------------------------- |
  | `AUTH_REQUIRED`             | No API key provided                     |
  | `AUTH_FAILED`               | API key not found or invalid            |
  | `CONNECTION_LIMIT`          | Server-wide cap reached                 |
  | `WILDCARD_CONNECTION_LIMIT` | Wildcard limit exceeded                 |
  | `SUBSCRIPTION_LIMIT`        | Max subscriptions reached               |
  | `ITEMS_PER_SUB_LIMIT`       | Too many items in one subscription      |
  | `ITEMS_LIMIT`               | Max total items reached                 |
  | `WILDCARD_NOT_ALLOWED`      | Plan doesn't support wildcards          |
  | `INVALID_FILTERS`           | Missing/invalid filter for this channel |
  | `SUBSCRIPTION_NOT_FOUND`    | Subscription ID doesn't exist           |
  | `PARSE_ERROR`               | Invalid JSON                            |
  | `UNKNOWN_ACTION`            | Unrecognized action                     |
  | `PLAN_REQUIRED`             | Feature requires a higher plan          |
  | `RATE_LIMIT`                | Sending messages too fast               |
</Expandable>