Partner Trades & Reconciliation

Audience

This surface is for partners running off-platform copies of the trade log — typically auditors and regulator-tech integrations. It is not for retail wallet flows; for a single user’s own trades use GET /api/me/trades. Two endpoints:

GET /api/v1/partner/trades — incremental, cross-wallet trade feed.
GET /api/v1/partner/reconciliation/snapshot — window-aggregate cross-check.

Authentication

Both endpoints use API-key auth.

Header: X-Api-Key: ps_live_<keyId>_<secret>
Required scope: partner:trades:read
The scope itself is read-only, but it is not exclusive: a key can carry partner:trades:read together with write scopes such as orders:write or vault:write. If you want an audit-only credential, ask for a key that holds partner:trades:read alone, and store any key that also holds a write scope as a trading credential.
Web-app user session tokens (Authorization: Bearer) are explicitly rejected on these endpoints — they are partner-only.
A multi_wallet key must still send X-User-Wallet on these requests, as on every request (see API keys); the feed itself is not filtered by that wallet.

Keys with this scope are issued by PredictStreet: ask your integration manager to add partner:trades:read to your key.

Trades feed

Cross-wallet executed-trade feed. Cursor-paginated and incremental by modification time.

GET /api/v1/partner/trades
X-Api-Key: ps_live_<keyId>_<secret>

Query parameters

Parameter	Type	Required	Default	Description
`modifiedSince`	ISO-8601 string	Yes	—	Returns trades whose `max(createdAt, settledAt)` is at or after this value.
`cursor`	string	No	`null`	Opaque token from the previous response’s `nextCursor`. Pass back unchanged.
`limit`	integer	No	`50`	Page size. Min 1, max 300.
`marketId`	string	No	—	Restrict results to a single market symbol.

Response — `200 OK`

{
  trades: PartnerTrade[];
  nextCursor: string | null;   // null when window fully drained
}

PartnerTrade:

{
  tradeId: string;             // upsert key
  status: 'matched' | 'settlement_pending' | 'settled' | 'settlement_failed';
  marketSymbol: string;
  marketTitle: string | null;
  eventId: string | null;
  eventTitle: string | null;
  categoryTags: string[];      // tag-id list
  matchedAt: string;           // ISO-8601, immutable
  settledAt: string | null;    // ISO-8601 once on-chain confirmed; on a
                               // settlement_failed trade it can be the failure time
  txHash: string | null;
  price: string;               // decimal, USDC — on binary markets quoted on the YES
                               // book: a party that traded NO paid / received 1 − price
  quantity: string;            // decimal, outcome-token units
  takerFee: PartnerTradeFee;   // taker leg's own fee
  makerFee: PartnerTradeFee;   // maker leg's own fee; both legs are charged
  taker: PartnerTradeSide;
  maker: PartnerTradeSide;
}

PartnerTradeFee:

{
  amount: string;                          // decimal
  currency: 'USDC' | 'OUTCOME_TOKENS';
  tokenId: string | null;                  // non-null iff currency='OUTCOME_TOKENS'
}

Both legs of a fill are charged, and each fee field carries the fee that leg paid. The fee take for one fill is takerFee + makerFee, so do not read takerFee as the trade total. A BUY leg is charged in OUTCOME_TOKENS and a SELL leg in USDC, so the two legs of one fill are often in different currencies: sum them per currency, and don’t convert OUTCOME_TOKENS to USDC without applying the trade price. A leg reads { amount: '0', currency: 'USDC', tokenId: null } only when it has no fee row: a settlement_failed trade (it never settled, so no fee was taken on either leg, even if an earlier pull showed one), trades from before 28 April 2026, or an in-flight trade whose row has not been written yet (that one shows its fee on a later pull). PartnerTradeSide (identical shape on taker and maker):

{
  side: 'BUY' | 'SELL';
  walletAddress: string;        // user EOA the order was signed from
  vaultAddress: string;         // smart-contract wallet that held collateral / outcome tokens
  orderId: string;
  orderType: 'LIMIT' | 'MARKET';
  orderTimeInForce: string;     // 'GTC' | 'IOC' | 'FOK'
  orderPlacedAt: string;        // ISO-8601
  orderOriginalQty: string;
  orderRemainingQty: string;    // the order's remaining quantity when this row was read
                                // (not a per-trade snapshot)
}

maker.side is always reported as the opposite of taker.side. On a binary-market fill where both parties bought (one YES, one NO) or both sold, the maker actually traded the same side as the taker.

Example

GET /api/v1/partner/trades?modifiedSince=2026-05-01T00:00:00Z&limit=50
X-Api-Key: ps_live_97f73727c6cd6859_xxx

{
  "trades": [
    {
      "tradeId": "1042",
      "status": "settled",
      "marketSymbol": "WC26-GROUP-A-ARG-MEX-1",
      "marketTitle": "Will Argentina beat Mexico?",
      "eventId": "evt_argmex_q1",
      "eventTitle": "Argentina vs Mexico",
      "categoryTags": ["world-cup", "group-stage"],
      "matchedAt": "2026-05-01T12:34:56.123456Z",
      "settledAt": "2026-05-01T12:35:12.789012Z",
      "txHash": "0xabc...",
      "price": "0.65",
      "quantity": "100.0",
      "takerFee": { "amount": "0.35", "currency": "OUTCOME_TOKENS", "tokenId": "8933...0217" },
      "makerFee": { "amount": "0.23", "currency": "USDC",           "tokenId": null },
      "taker": {
        "side": "BUY",
        "walletAddress": "0x014eab...",
        "vaultAddress":  "0x3ef9a2...",
        "orderId": "ord_xyz",
        "orderType": "LIMIT",
        "orderTimeInForce": "GTC",
        "orderPlacedAt": "2026-05-01T12:30:00.000000Z",
        "orderOriginalQty": "100.0",
        "orderRemainingQty": "0"
      },
      "maker": { /* same shape */ }
    }
  ],
  "nextCursor": "eyJ0cyI6IjIwMjYtMDUtMDFUMTI6MzQ6NTYuMTIzNDU2WiIsImlkIjoiMTA0MiJ9"
}

Behaviour notes

Idempotency. A single trade may surface twice — once when matched (status='matched', settledAt: null), again when settlement lands (status='settled', settledAt: <iso>). Partners are expected to upsert by tradeId.
In-walk re-emit. The same trade can re-emit within a single cursor walk if its settlement lands between page N and N+1. Same upsert rule applies.
modifiedSince must stay constant across all cursor pages of a single drain.
Settlement failures are included with status='settlement_failed' — do NOT filter them out client-side. A failure does not always move modifiedAt, so a trade you stored as matched or settlement_pending can fail without showing up again on your incremental pull. Periodically re-pull a trailing window (for example modifiedSince = now − 24 h) and upsert, so rows that were not yet final pick up their final status.

Status codes

Code	When
`200`	Success (incl. empty `trades: []` page)
`400`	Malformed query (see Errors)
`401`	Missing or invalid `X-Api-Key`
`403`	Authenticated but key lacks `partner:trades:read`, or JWT used instead of API-key
`429`	Rate limit exceeded
`5xx`	Internal failure (transient — retry with exponential backoff)

Rate limit

Per partner (one bucket shared by all of your API keys): 600 requests / minute by default. The limit scales with your account’s rate tier, which PredictStreet can raise.
Per IP: 1000 requests / minute (defence-in-depth on egress IP).

Reconciliation snapshot

Window-aggregate cross-check for a partner’s local copy of trades. Returns counts, sums, and a deterministic content hash over the trade ids in the window.

GET /api/v1/partner/reconciliation/snapshot
X-Api-Key: ps_live_<keyId>_<secret>

Query parameters

Parameter	Type	Required	Description
`from`	ISO-8601 string	Yes	Inclusive lower bound. Compared against `max(createdAt, settledAt)`.
`to`	ISO-8601 string	Yes	Exclusive upper bound. Window length capped at 24 hours.

The from / to bounds use the same max(createdAt, settledAt) expression as the trade feed’s modifiedSince. The window aligns 1:1 with trades the partner pulled via ?modifiedSince=.

Response — `200 OK`

{
  window: { from: string; to: string };
  totals: {
    tradeCount: number;
    totalQuantity: string;             // decimal, outcome-token units
    totalUsdcVolume: string;           // SUM(price * quantity), USDC
    totalTakerFeesUsdc: string;        // taker-leg fees in USDC over window
    totalTakerFeesOutcomeTokens: Array<{
      tokenId: string;
      amount: string;
    }>;                                // taker-leg fees by outcome token
    totalMakerFeesUsdc: string;        // maker-leg fees in USDC over window
    totalMakerFeesOutcomeTokens: Array<{
      tokenId: string;
      amount: string;
    }>;                                // maker-leg fees by outcome token
  };
  fingerprint: {
    algorithm: 'sha256-csv-trade-ids';
    value: string;                     // 64-char lowercase hex
  };
  computedAt: string;                  // ISO-8601
}

The fee take over the window is the taker totals plus the maker totals, summed per currency.

Fingerprint algorithm

sha256 of the trade ids in the window, sorted lexicographically as decimal strings and joined by commas:

import hashlib
ids = sorted(str(t.tradeId) for t in trades_in_window)   # string sort
fp  = hashlib.sha256(",".join(ids).encode()).hexdigest()

Sort as strings, not as integers. ["1", "10", "2"], not ["1", "2", "10"]. The server matches the default sort order in Python / JavaScript / Go.

Empty-window canonical (no trades in [from, to)): e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (SHA-256 of the empty string).

Stability

Field	Stability
`tradeCount`, `totalQuantity`, `totalUsdcVolume`, `fingerprint`	Can change until every trade counted in the window is final. Membership is keyed on `max(createdAt, settledAt)`, so a trade matched before `to` that settles after `to` moves out of this window into the one that contains its `settledAt`.
`totalTakerFeesUsdc`, `totalTakerFeesOutcomeTokens`, `totalMakerFeesUsdc`, `totalMakerFeesOutcomeTokens`	Fee rows are written together with the trade at match time. They are removed if the trade ends in `settlement_failed`, so fee totals can go down for a window that contains such a trade.

Snapshots of past windows are cached for up to 1 hour, live windows for 60 seconds.

Status codes

Code	When
`200`	Success
`400`	`invalid_request` (missing or malformed `from` / `to`), `invalid_window` (`from` ≥ `to`), `window_too_large` (> 24 h)
`401`	Missing or invalid `X-Api-Key`
`403`	Scope missing or JWT used instead of API-key
`429`	Rate limit exceeded
`5xx`	Internal failure

Rate limit

Per partner (shared by all of your API keys): 60 requests / minute by default, scaled by the same account rate tier (recon is meant for periodic polling, not high-frequency).
Per IP: 200 requests / minute.

Error envelope

All errors use the platform error envelope:

{
  status: number;              // HTTP status, repeated
  error: {
    code: string;
    message: string;
    trace_id?: string;         // quote this to support
    retryAfterSec?: number;    // on 429
    details?: object;          // e.g. `fields` on validation errors
  };
}

Codes used by these endpoints

HTTP	`code`	Meaning
400	`invalid_request`	Missing or malformed query parameter (`modifiedSince`, `from`, `to`, `limit` outside 1–300, unknown parameter); `error.details.fields` lists them
400	`invalid_cursor`	Cursor is malformed / not produced by us
400	`invalid_window`	`from` ≥ `to`
400	`window_too_large`	Reconciliation window > 24 hours
401	`auth_required`	No `X-Api-Key` header
401	`api_key_<reason>` (e.g. `api_key_bad_format`, `api_key_unknown_key`)	Key malformed, unknown, revoked or otherwise rejected — see Error codes
403	`api_key_required_not_jwt`	Authenticated as JWT user; this surface is API-key-only
403	`api_key_scope_missing`	API key valid but lacks `partner:trades:read` scope
429	`rate_limited`	Rate limit exceeded — wait `error.retryAfterSec` (also sent as the `Retry-After` header)
5xx	`internal_error`	Transient — retry with exponential backoff

Getting Started

Authentication

Vaults

Deposits

Trading

Events & Tags

Markets

Portfolio

Withdrawals

WebSocket

Settlement & Oracle

On-chain Contracts

Partners

Errors

Partner Trades & Reconciliation

Audience

Authentication

Trades feed

Query parameters

Response — `200 OK`

Example

Behaviour notes

Status codes

Rate limit

Reconciliation snapshot

Query parameters

Response — `200 OK`

Fingerprint algorithm

Stability

Status codes

Rate limit

Error envelope

Codes used by these endpoints

​Audience

​Authentication

​Trades feed

​Query parameters

​Response — 200 OK

​Example

​Behaviour notes

​Status codes

​Rate limit

​Reconciliation snapshot

​Query parameters

​Response — 200 OK

​Fingerprint algorithm

​Stability

​Status codes

​Rate limit

​Error envelope

​Codes used by these endpoints

Audience

Authentication

Trades feed

Query parameters

Response — `200 OK`

Example

Behaviour notes

Status codes

Rate limit

Reconciliation snapshot

Query parameters

Response — `200 OK`

Fingerprint algorithm

Stability

Status codes

Rate limit

Error envelope

Codes used by these endpoints