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

# Trades

> Trade history with filters and lifecycle status.

## List your trades

```http theme={null}
GET /api/me/trades?limit=200&marketId=...
X-Api-Key: ps_live_<keyId>_<secret>  # integrators — needs `portfolio:read`
```

Reverse-chronological. Paginate with the opaque [`cursor`](#pagination)
echoed back as `nextCursor`. `limit` is capped at 200 (default 50).

Response:

```json theme={null}
{
  "walletAddress": "0x251e6986…",
  "nextCursor": "eyJjIjoiMjAyNi0wNC0yMlQxMDozMTo0Mi4xMTlaIiwiaWQiOiI2ZjNiIn0",
  "trades": [
    {
      "id": "6f3b…-uuid",
      "orderId": "0x...",
      "userWallet": "0x...",
      "marketId": "UAE-CUP-FINAL-20260425",
      "price": "0.5140",
      "quantity": "100",
      "fee": "0.2496",
      "side": "buy",
      "createdAt": "2026-04-22T10:31:42.119Z",
      "status": "settled",
      "txHash": "0x39007378…b54637f4b8",
      "settledAt": "2026-04-22T10:31:48.301Z",
      "adjustment": "NONE"
    }
  ]
}
```

### Pagination

This feed is **keyset-paginated** — the same scheme as `/api/me/orders/open`
and [`/api/me/portfolio/positions`](/concepts/portfolio/positions).

* Each response carries a `nextCursor` — an **opaque** token. Pass it back as
  `?cursor=<nextCursor>` to fetch the next (older) page. Treat it as a black
  box; don't parse or construct it.
* `nextCursor` is `null` only on the **last** page — never a silent
  truncation. Keep requesting until it's `null`.
* `limit` caps the page size (max **200**, default 50).
* The legacy `?before=<ISO-8601>` parameter still works for backward
  compatibility, but prefer `cursor` — it carries a unique tiebreaker so rows
  sharing the same `createdAt` (common when one match writes several rows) are
  never skipped or duplicated at a page boundary.

```http theme={null}
# page 1
GET /api/me/trades?limit=200
# page 2 — feed back the previous response's nextCursor
GET /api/me/trades?limit=200&cursor=eyJjIjoiMjAyNi0wNC0yMlQxMDozMTo0Mi4xMTlaIiwiaWQiOiI2ZjNiIn0
```

### Fields

| Field                         | Description                                                                                                |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `id`                          | Trade UUID.                                                                                                |
| `orderId`                     | The wallet's own order on this fill (maker or taker side).                                                 |
| `userWallet` / `vaultAddress` | EOA + bound vault.                                                                                         |
| `marketId`                    | `admin.markets.symbol`.                                                                                    |
| `price` / `quantity`          | Decimal strings (8-decimal precision).                                                                     |
| `fee`                         | Quadratic taker fee charged on this fill — decimal-string USDC. Maker rows are always `0`.                 |
| `side`                        | `buy` or `sell` from the wallet's own perspective (taker side stored on the row, flipped for maker fills). |
| `createdAt`                   | ISO-8601 — when matcher recorded the cross.                                                                |
| `status`                      | Trade lifecycle. See [Lifecycle](#lifecycle).                                                              |
| `txHash`                      | On-chain settlement tx; `null` until the match-submitter broadcasts.                                       |
| `settledAt`                   | ISO-8601 of the chain settlement-confirmation event; `null` while `status !== "settled"`.                  |
| `adjustment`                  | Matcher-supplied chain-settlement classifier (BR-MC-BIN-01). See [Adjustment](#adjustment).                |

### Lifecycle

A trade row is created on the matcher confirming a cross and progresses
through a small set of public statuses until the chain-side
settlement lands.

| `status`             | Meaning                                                                                                         | `txHash` populated? | `settledAt` populated? |
| -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------- |
| `matched`            | Matcher confirmed the cross. The trade leg has not yet been broadcast on-chain.                                 | No                  | No                     |
| `settlement_pending` | `match-submitter` signed and broadcast the on-chain settlement tx. Awaiting block + chain-watcher confirmation. | Yes                 | No                     |
| `settled`            | On-chain settlement confirmed; balances and ERC-1155 positions have been mirrored off-chain.                    | Yes                 | Yes                    |

The `settlement_failed` state is **not** exposed on this feed — that's
an ops-only signal for chain reverts and is filtered server-side. If
your integration relies on `txHash` finality, gate on
`status === "settled"` and `settledAt != null`.

### Adjustment

`adjustment` reflects the chain mechanism that backed the trade:

| Value            | When                                                                                                               | What happens on-chain                                                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NONE` (default) | Two parties cross on the same outcome (one is buyer, the other is seller of the same token)                        | Direct ERC-1155 transfer for the outcome token; USDC transfer for the price.                                                                                   |
| `MINT`           | Two parties cross on **opposite** outcomes (both are buyers — one of YES, one of NO — and the prices sum to \~\$1) | Operator calls `Vault.splitPosition` to mint a fresh complete set of YES + NO from collateral. Each party receives the side they bought; both contribute USDC. |
| `BURN`           | Two parties cross on **opposite** outcomes (both are sellers, prices sum to \~\$1)                                 | Operator calls `Vault.mergePositions` to redeem the complete set into USDC; both sellers receive USDC.                                                         |

`MINT` / `BURN` are produced exclusively on `is_binary=true` markets
where the matcher canonicalises every order onto the YES book and
treats opposite-side BUYs (or opposite-side SELLs) as cross-outcome
matches. On non-binary markets every fill is `NONE`. On a binary
market where both sides shared the same outcome (a same-side cross on
the canonical YES book) the row is also `NONE`.

## Fills for a single order

```http theme={null}
GET /api/orders/{orderId}/fills
```

Returns the same `Trade` shape, scoped to fills that touched a
specific order.

## Real-time

Three WebSocket channels surface the same lifecycle:

* `user_fills` — emitted on `matched` for every wallet fill.
* `chain.fill_settled` (via `vault_positions` and `vault_activity`) —
  fires on `settled` with the chain-confirmed balance changes.
* `token_trade_settlements` — public per-token feed of settled trades.

See [WebSocket reference](/api-reference/websocket/overview).