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

# Pending Trades

> Get trade events 3–5 seconds early from the Polygon mempool

<Info>
  Pending trade events are available on Dev, Pro, and Enterprise plans.
</Info>

Pending events are detected from the Polygon mempool **before** the transaction is mined. They arrive on average **\~3 seconds** before the corresponding confirmed event, typically **3–5 seconds** early.

This gives you an early signal for copytrading, alerting, or analytics - before the trade is finalized on-chain.

## How It Works

1. A trade transaction enters the Polygon mempool
2. Predexon detects it and emits a **pending** event
3. \~3–5 seconds later, the transaction is mined and a **confirmed** event is emitted
4. Match the two events by `tx_hash` - the confirmed event supersedes the pending one

## Enabling Pending Events

Add a `status` filter to your orders subscription. There are three modes:

| `status` Value          | What You Receive                | 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.

<Note>
  Free-tier keys cannot request pending events. Subscribing with `status: "all"` or `status: "pending"` on Free returns `PLAN_REQUIRED`. Free tier continues to receive confirmed events on the default (`"confirmed"`) as before.
</Note>

### Subscribe to both pending and confirmed

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

### Subscribe to pending only

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

### Update an existing subscription

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

***

## What Differs Between Pending and Confirmed

Every `order_filled` event includes a `status` field (`"pending"` or `"confirmed"`). Most fields are identical, but a few differ:

| Field                          | Pending              | Confirmed       | Why                                                                            |
| ------------------------------ | -------------------- | --------------- | ------------------------------------------------------------------------------ |
| `status`                       | `"pending"`          | `"confirmed"`   |                                                                                |
| `price`                        | May differ slightly  | Exact           | Can differ by a fraction of a cent if partial fills change the effective price |
| `shares` / `shares_normalized` | May differ slightly  | Exact           | If the tx partially fills, final on-chain amounts may differ                   |
| `fee`                          | Estimated            | Exact           | Actual fee may vary slightly after on-chain settlement                         |
| `log_index`                    | `null`               | Integer         | No log exists yet for pending                                                  |
| `order_hash`                   | String               | String          | Now included in both pending and confirmed events                              |
| `timestamp`                    | Time seen in mempool | Block timestamp |                                                                                |
| `tx_hash`                      | Exact                | Exact           | Same hash - use this to match pending → confirmed                              |

All other fields - `user`, `taker`, `token_id`, `side`, and all metadata (market slug, title, outcome, etc.) - are **identical** between pending and confirmed.

***

## Important Caveats

* **Not guaranteed to confirm** - some pending transactions may be dropped, reverted, or replaced. Treat `status: "pending"` as a strong signal, not a guarantee.
* **Only `order_filled` events** - pending detection applies to trade fills only. Fee refunds, activity, and lifecycle events remain confirmed-only.
* **Match by `tx_hash`** - when the confirmed event arrives, it supersedes the pending one. Use `tx_hash` to correlate them.

***

## Example: Handling Both Pending and Confirmed

```javascript theme={null}
const pendingTrades = new Map(); // tx_hash → pending data

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.type === 'event' && msg.data.event_type === 'order_filled') {
    const data = msg.data;

    if (data.status === 'pending') {
      // Early signal from mempool - act on it, but expect confirmation
      pendingTrades.set(data.tx_hash, data);
      console.log(`[PENDING] ${data.side} ${data.outcome} ${data.shares_normalized} @ ${data.price}`);
      console.log(`  Market: ${data.title}`);
      console.log(`  Maker: ${data.user}`);
    }

    if (data.status === 'confirmed') {
      const wasPending = pendingTrades.delete(data.tx_hash);
      const label = wasPending ? '[CONFIRMED]' : '[NEW]';
      const value = data.shares_normalized * data.price;
      console.log(`${label} ${data.side} ${data.outcome} ${data.shares_normalized} @ ${data.price}`);
      console.log(`  Market: ${data.title}`);
      console.log(`  Value: $${value.toFixed(2)}`);
    }
  }
};
```