Order lifecycle

​

State machine

​

States

​

Filtering /api/orders/open

GET /api/orders/open?marketId=NCAA-FINAL-WINNER-93920000&side=buy&outcome=0

​

Trade-level settlement (after match)

​

How partners observe settlement

• WebSocket /ws/user typed channels (recommended). On an API key, every channel below needs the portfolio:read scope — a key with only orders:write is refused with api_key_scope_missing:
  • user_orders — order_placed / order_cancelled / order_rejected / order_expired. Use for orderbook UI updates. It also carries trade_failed (see below).
  • user_fills — user_fill fires at match time (source: "matcher"), before on-chain settlement. It carries no fee, txHash or blockNumber.
  • vault_activity (subscribe with ids: [<your vault address>]; any other vault address is refused) — trade_fill fires when the on-chain OrderFilled event for your vault is indexed. It carries txHash, blockNumber, orderHash, fee, both vault addresses (makerVault / takerVault) and the filled amounts. side ("maker" / "taker") is your vault’s position in that OrderFilled event, not your order’s role in the match: a taker order that fills against N resting orders produces N frames with side: "taker" plus one side: "maker" frame for the taker order’s own fill.
• REST balance polling — available + locked totals derive from on-chain-confirmed state, so polling /api/me/balances is a backstop if WS is unavailable.
• Settlement-leg failures — when the chain rejects a leg (MatchFailed), the taker receives a trade_failed frame on user_orders (orderId there is the taker order’s EIP-712 hash). The maker side gets no trade_failed, so also poll GET /api/orders/{id}: the failed quantity comes off filledQty, and the order moves back to OPEN / PARTIAL or ends SETTLEMENT_FAILED (a SETTLEMENT_FAILED order’s locked balance is refunded automatically — the trade is treated as if it never settled).

​

What actually happens on POST /api/orders/place

1. Authn — X-Api-Key is verified (partner lookup → SHA-256 hash compare → key lifecycle checks). The acting wallet is your key’s associatedWallet (single_wallet keys) or the X-User-Wallet header (multi_wallet keys). orders:write scope is enforced before the handler runs — see API keys.
2. Market guard — the market must be OPEN, or PRE_MARKET for resting LIMIT GTC orders that don’t cross the book. It is checked before the signature is verified and re-checked when funds are locked (step 5). A failure comes back in the normal 201 response with status: REJECTED and code: market_not_open (market not open, or its close cut-off has passed), pre_market_post_only (non-LIMIT-GTC order in pre-market) or pre_market_crossing_order (pre-market order would cross).
3. Pre-verify enrichment — the platform resolves:
   • your vault via VaultFactory.vaultOf(signer)
   • the on-chain tokenId for the requested outcome
   • makerAmount / takerAmount from price × quantity per side
4. EIP-712 verify — the platform rebuilds the on-chain Order struct (11 fields) itself. It does not take maker or signatureType from you:
   • salt = body nonce
   • maker = your vault (VaultFactory.vaultOf(signer))
   • signer = the acting wallet
   • taker = 0x0000000000000000000000000000000000000000
   • tokenId = the token of the requested outcome
   • makerAmount / takerAmount from price × quantity at 6 decimals (BUY notional rounded up, SELL rounded down)
   • expiration = body expiry
   • feeRateBps = the market’s current feeTakerBps
   • side = 0 BUY / 1 SELL
   • signatureType = 1 (VAULT), always
   The digest uses the binary or neg-risk exchange domain, depending on the market. Your signature must recover to the acting wallet over exactly this struct. If it does not, the order comes back REJECTED with code: bad_signature, and details.recovered, details.expected_signer and details.platform_canonical_struct let you diff your struct against ours. A BUY signed with a rounded-down notional is rejected as order_signed_with_floor_notional instead (details.expectedCeilMakerAmountWei is the value to sign). A non-zero expiry that has already passed also reports bad_signature; if the signature itself is correct, recovered then equals expected_signer. The body maker only has to be your wallet or your vault (anything else is 401 maker_mismatch); either way, the vault is what gets signed over and stored.
5. Balance / position lock — atomic:
   • BUY: available -= notional, locked += notional
   • SELL: position lookup is keyed by vault address (not EOA); fails with insufficient_position if the vault doesn’t hold enough of the outcome token
   • the order row is recorded as PENDING
6. Match — sent to the matching engine. Returns {status, filledQty, trades[]} synchronously.
7. Trade persistence — trade rows + fee ledger written, balance deltas applied for both sides of every trade — atomically.
8. Settlement enqueue — matched trades are broadcast on-chain via batchMatchOrders on CTFExchange. See the trade-state table above.
9. Response — shape documented below.

​

Response shape

interface PlaceOrderResp {
  orderId: string;
  status:
    | 'PENDING'
    | 'OPEN'
    | 'FILLED'
    | 'CANCELLED'
    | 'REJECTED'
    | 'EXPIRED'
    | 'SETTLEMENT_FAILED';
  filledQty: string;
  remainingQty: string;
  trades: Trade[];
  code?: string;
  message?: string;
}

interface Trade {
  id: string;
  orderId: string;
  userWallet: string;        // EOA — the side's authenticated wallet
  marketId: string;
  price: string;             // decimal USDC
  quantity: string;          // outcome-token qty (decimal)
  fee: string;               // trade-level fee in USDC, k × P × (1 − P) × quantity; a BUY leg is
                             // actually charged in outcome tokens, so read the per-leg fee from
                             // /api/orders/{id}/fills or /api/me/fees
  side: 'buy' | 'sell';      // from this wallet's perspective
  createdAt: string;
}

​

Idempotency

​

Cancellation

POST /api/orders/cancel
X-Api-Key: ps_live_<keyId>_<secret>  # integrators — needs `orders:write`
Content-Type: application/json

{ "orderId": "3f6c1a2e-8b4d-4c1e-9a7f-2d5e6b7c8d90" }

• On success the order ends as CANCELLED and the locked collateral for its unfilled remainder returns to available.
• Cancelling an order that has already ended answers already_terminal, so a repeated cancel is safe. See Cancelling orders.

​

Next