Trades

List your trades

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 echoed back as nextCursor. limit is capped at 200 (default 50). To fetch only what is new since a point in time, add after and follow Polling for new trades. Response:

{
  "walletAddress": "0x251e6986…",
  "nextCursor": "eyJjIjoiMjAyNi0wNC0yMlQxMDozMTo0Mi4xMTkwMDBaIiwiaWQiOiIxNDk3MzEyOSJ9",
  "trades": [
    {
      "id": "14973129",
      "orderId": "3f6c…-uuid",
      "userWallet": "0x...",
      "marketId": "UAE-CUP-FINAL-20260425",
      "price": "0.510000000000000000",
      "quantity": "100.000000000000000000",
      "fee": "1.944000000000000000",
      "feeUnit": "OUTCOME_TOKENS",
      "feeTokenId": "82767994009884018025111405605018065315304321056376041259837064758376184740876",
      "side": "buy",
      "outcomeIndex": 0,
      "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/fees and /api/me/balance-events.

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.

# page 1
GET /api/me/trades?limit=200
# page 2 — feed back the previous response's nextCursor
GET /api/me/trades?limit=200&cursor=eyJjIjoiMjAyNi0wNC0yMlQxMDozMTo0Mi4xMTkwMDBaIiwiaWQiOiIxNDk3MzEyOSJ9

Fetching trades after a time

after=<ISO-8601> returns only trades whose createdAt is strictly later than that instant. It combines with cursor, before and marketId, and the feed still runs newest first.

Send an explicit zone, Z or ±hh:mm: 2026-10-01T08:30:00Z or 2026-10-01T10:30:00.250400+02:00. Up to microseconds are honoured. A time without a zone is rejected with 400 invalid_timestamp, not guessed.
Page with nextCursor until it is null. The cursor carries after, so cursor=<nextCursor> on its own stays inside the window.
An after in the future returns an empty page.
If you also send before without a cursor, after must be earlier than it; otherwise the answer is 400 invalid_range.

# trades since T, newest first
GET /api/me/trades?limit=200&after=2026-10-01T08:29:00Z
# next page: the cursor keeps the same after
GET /api/me/trades?limit=200&cursor=<nextCursor>

Polling for new trades

createdAt is the time matching started, not the moment the trade became visible here. A trade can therefore appear after one with a later createdAt. Poll with an overlap:

Set after to the newest createdAt you have seen minus 60 seconds.
Page until nextCursor is null.
Upsert by id. The overlap returns trades you already have.

Setting after to exactly the newest createdAt you have seen can miss a trade for good. Always keep the 60-second overlap.

after selects trades by creation time only. A trade you already have is not returned again when its status, txHash or settledAt changes. Keys with the partner:trades:read scope can follow those changes on the partner trades feed (modifiedSince).

Fields

Field	Description
`id`	Trade id — a numeric string (e.g. `"14973129"`), the same value as `tradeId` on `/api/me/fees` and `/api/me/balance-events` rows. Store and compare it as a string.
`orderId`	The wallet’s own order on this fill (maker or taker side).
`userWallet` / `vaultAddress`	EOA + bound vault.
`marketId`	The market `symbol`.
`price` / `quantity`	Decimal strings with up to 18 decimal places (e.g. `"0.510000000000000000"`); parse them as decimals and don’t assume a fixed scale. `price` is for the wallet’s own outcome: on a NO-side fill of a YES/NO market it is 1 minus the YES-book price.
`fee`	Quadratic fee charged on this fill (decimal string). Read `feeUnit` before interpreting — this is dollars only when `feeUnit="USDC"`, and outcome tokens when `feeUnit="OUTCOME_TOKENS"`. Both legs are charged; see Fees.
`feeUnit`	Denomination of `fee`: `USDC` on SELL legs, `OUTCOME_TOKENS` on BUY legs (the in-kind share haircut). Historical trades carrying no per-side fee-ledger row for this leg fall back to `USDC` with the trade-level collateral fee, so an old BUY leg can read `USDC`. The per-side row is written in the same transaction as the trade, so this is not a transient state on current trades and it does not resolve as the trade settles — don’t poll `status` waiting for it to correct.
`feeTokenId`	ERC-1155 outcome tokenId the fee was charged in. Non-null exactly when `feeUnit="OUTCOME_TOKENS"`.
`side`	`buy` or `sell` — what the wallet’s own order did on this fill. On `MINT` fills both parties show `buy`; on `BURN` fills both show `sell`.
`outcomeIndex`	Wallet-side outcome index for this trade. On binary YES/NO markets, `0` is YES and `1` is NO.
`groupItemImageUrl`	Per-outcome contestant/team logo, so a trade feed can render the bundle sub-question icon. `null` on markets without a logo set.
`createdAt`	ISO-8601 — when matcher recorded the cross.
`status`	Trade lifecycle. See Lifecycle.
`txHash`	On-chain settlement tx; `null` until the platform broadcasts it.
`settledAt`	ISO-8601 of the chain settlement-confirmation event; `null` while `status !== "settled"`.
`adjustment`	Chain-settlement classifier attached to the fill. See 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`	The platform signed and broadcast the on-chain settlement tx. Awaiting block 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)	The exchange contract splits the pooled USDC into a fresh YES + NO set as part of settlement. Each party receives the side they bought; both contribute USDC.
`BURN`	Two parties cross on opposite outcomes (both are sellers, prices sum to ~$1)	The exchange contract merges the YES + NO pair back into USDC as part of settlement; both sellers receive USDC.

MINT / BURN occur only on YES/NO markets that match every order on a single YES book, where opposite-outcome BUYs (or SELLs) can cross each other. On other markets every fill is NONE, and so is a fill where both sides traded the same outcome.

Fills for a single order

GET /api/orders/{orderId}/fills
X-Api-Key: ps_live_<keyId>_<secret>  # needs `orders:read`

Returns { orderId, trades }: each trades entry has the same Trade shape (without groupItemImageUrl), oldest first, for the fills that touched this order. An order id you don’t own, or one that doesn’t exist, returns 200 with trades: [] rather than 404.

Real-time

Three WebSocket channels surface the same lifecycle:

user_fills — emitted on matched for every wallet fill.
vault_activity (trade_fill) and vault_positions (vault_position_balance_changed) — fire when the fill settles on-chain, with the chain-confirmed balance changes.
token_trade_settlements — public per-token feed of settled trades.

See WebSocket reference.

Getting Started

Authentication

Vaults

Deposits

Trading

Events & Tags

Markets

Portfolio

Withdrawals

WebSocket

Settlement & Oracle

On-chain Contracts

Partners

Errors

List your trades

Fetching trades after a time

Polling for new trades

Fields

Lifecycle

Adjustment

Fills for a single order

Real-time

​List your trades

​Pagination

​Fetching trades after a time

​Polling for new trades

​Fields

​Lifecycle

​Adjustment

​Fills for a single order

​Real-time

List your trades

Pagination

Fetching trades after a time

Polling for new trades

Fields

Lifecycle

Adjustment

Fills for a single order

Real-time