> For the complete documentation index, see [llms.txt](https://sm-fund.gitbook.io/sm-fund-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sm-fund.gitbook.io/sm-fund-docs/reference/polymarket-feed.md).

# Polymarket feed

The Polymarket feed is a server-push WebSocket stream of complete pending `matchOrders` TradeBatch messages.

| Item               | Value                                                                  |
| ------------------ | ---------------------------------------------------------------------- |
| URL                | `wss://stream.sm.fund/ws` or `wss://stream.sm.fund/ws?feed=polymarket` |
| Subprotocol        | `mmp.trade-batch.v1`                                                   |
| Authentication     | `Authorization: Bearer <WSS_TICKET>`                                   |
| Server frame       | UTF-8 JSON text                                                        |
| Client data frames | Not supported; the connection closes with `1008`                       |

Obtain the ticket from [the ticket endpoint](/sm-fund-docs/reference/tickets.md). The API key stays on the server that calls the ticket endpoint; it is never sent to this WebSocket.

## Message shape

Each accepted transaction is one JSON frame. This example uses fictional transaction and wallet identifiers:

```json
{
  "schema_version": 1,
  "event_type": "pending_trade_batch",
  "chain_id": 137,
  "tx_hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
  "condition_id": "0x2222222222222222222222222222222222222222222222222222222222222222",
  "fills": [
    {
      "fill_index": 0,
      "maker": "0x3333333333333333333333333333333333333333",
      "signer": "0x4444444444444444444444444444444444444444",
      "token_id": "123456789012345678901234567890",
      "side": "BUY",
      "price": "0.4",
      "size": "10",
      "order_role": "taker",
      "match_type": null,
      "shares_raw": "10000000",
      "usdc_raw": "4000000",
      "fee_raw": "0"
    },
    {
      "fill_index": 1,
      "maker": "0x5555555555555555555555555555555555555555",
      "signer": "0x6666666666666666666666666666666666666666",
      "token_id": "987654321098765432109876543210",
      "side": "BUY",
      "price": "0.6",
      "size": "10",
      "order_role": "maker",
      "match_type": "MINT",
      "shares_raw": "10000000",
      "usdc_raw": "6000000",
      "fee_raw": "0"
    }
  ]
}
```

### Top-level fields

| Field            | Type and value                       | Meaning                                                          |
| ---------------- | ------------------------------------ | ---------------------------------------------------------------- |
| `schema_version` | integer, always `1`                  | Public message schema version.                                   |
| `event_type`     | string, always `pending_trade_batch` | Identifies a pending batch; it is not chain confirmation.        |
| `chain_id`       | integer, always `137`                | Polygon chain ID.                                                |
| `tx_hash`        | string                               | Pending transaction hash and batch de-duplication key.           |
| `condition_id`   | string                               | Condition ID from the `matchOrders` calldata.                    |
| `fills`          | array                                | All taker and maker fills from this calldata, in calldata order. |

### Fill fields

| Field        | Type and value                              | Meaning                                                                |
| ------------ | ------------------------------------------- | ---------------------------------------------------------------------- |
| `fill_index` | integer                                     | `0` is the taker order; `1..n` follows `makerOrders[]`.                |
| `maker`      | address string                              | The order's maker address; filter participant wallets with this field. |
| `signer`     | address string                              | The order's signer address.                                            |
| `token_id`   | decimal string                              | Outcome token ID.                                                      |
| `side`       | `BUY` or `SELL`                             | Order side.                                                            |
| `price`      | decimal string                              | Normalized fill price.                                                 |
| `size`       | decimal string                              | Normalized share quantity.                                             |
| `order_role` | `taker` or `maker`                          | Role of the order in the fill.                                         |
| `match_type` | `COMPLEMENTARY`, `MINT`, `MERGE`, or `null` | Maker match type; the taker fill is `null`.                            |
| `shares_raw` | decimal string                              | Exact share integer.                                                   |
| `usdc_raw`   | decimal string                              | Exact USDC integer.                                                    |
| `fee_raw`    | decimal string                              | Calldata fill fee integer.                                             |

Treat all numeric strings as strings. Use `tx_hash` to de-duplicate a batch and `(tx_hash, fill_index)` to identify a fill. A batch is emitted only after all fills are valid; an invalid fill causes the complete batch to be dropped.

The stream has no replay, cursor, or acknowledgement mechanism. A disconnect, restart, or slow consumer can leave a gap. Message order is not chain order or finality.

## Connection behavior

Free adds a fixed 500 ms delivery delay; Developer adds no delivery delay. The delay is applied per event and does not accumulate one 500 ms wait after another. Both feeds share one connection per user across all API keys. A newer valid connection closes the previous one with `4001 connection replaced`; see [error handling](/sm-fund-docs/reference/errors.md) for reconnect guidance. See [plans and billing](/sm-fund-docs/get-started/plans-and-billing.md) for plan details.

The feed is server-push only. Respond to WebSocket ping frames according to your client library, and do not send application text or binary frames.