Trades

Trade history with filters and lifecycle status.

List your trades

GET /api/me/trades?before=2026-04-30T00:00:00Z&marketId=...&limit=200
X-Api-Key: ps_live_<keyId>_<secret>  # integrators — needs `portfolio:read`

Response:

{
  "walletAddress": "0x251e6986…",
  "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"
    }
  ]
}

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

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

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.