API Reference

Services & base URLs

In-browser calls to the Trading API go through the same-origin proxy /api/pmj/v1/… (the gateway sends no CORS headers; the proxy forwards REST only). Switching environments changes only the host — paths and semantics are identical.

Matching-engine design principles

The following mechanisms define the API semantics.

GatewayCommand logMatching engineProjections / market dataClearingOn-chain settlement (Sui)

Four hard contracts

1. 202 = the command is persisted ≠ it has traded. After a write is accepted, use the cursor from the response body together with the status endpoint to confirm the outcome.
2. cursor is an opaque string. The only promise is that you may pass it back verbatim to the same market endpoint as minCursor — nothing is promised about its structure, and it is not comparable.
3. minCursor is only meaningful on single-market queries. Cross-partition and cross-time endpoints (the markets list, positions, trades, candles) return 400 outright.
4. 404 has two meanings, indistinguishably. Either the projection has not caught up, or the resource really is absent; the responses are byte-for-byte identical. Retry the first 404 with the cursor — it is not a terminal state.

Units: prices in *E4 (1e-4 USD), sizes in *E2 (1e-2 shares), amounts in *E6 (1e-6 USD). Fixed-point integers throughout; no floating point in any example.

Quickstart: the order loop

curl -X POST "http://127.0.0.1:8090/api/v1/auth/nonce" \
  -H "Content-Type: application/json" \
  -d '{"address":"0x…"}'
# → {nonce, message, expiresAt}
# Hand message to the wallet's signPersonalMessage as-is, then:
curl -X POST "http://127.0.0.1:8090/api/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{"address":"0x…","signature":"<sig>","bytes":"<bytes>"}'
# → {token, address, expiresAt}

curl "http://127.0.0.1:8090/api/v1/markets?status=open&limit=20"

curl "http://127.0.0.1:8090/api/v1/markets/mkt-0001/book?depth=10"

curl "http://127.0.0.1:8090/api/v1/accounts/0x…" \
  -H "Authorization: Bearer $PMJ_TOKEN"

curl -X POST "http://127.0.0.1:8090/api/v1/orders" \
  -H "Authorization: Bearer $PMJ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"marketId":"mkt-0001","outcome":"YES","side":"BUY","priceE4":5200,"sizeE2":1000,"postOnly":false,"clientOrderId":"my-idempotency-key-1"}'
# → 202 {orderId, clientOrderId, cursor, commandId}

curl "http://127.0.0.1:8090/api/v1/markets/mkt-0001/orders/<orderId>?minCursor=<cursor>" \
  -H "Authorization: Bearer $PMJ_TOKEN"
# → 200 {status: "OPEN"|"PARTIAL"|"FILLED"|"CANCELLED", filledE2, …}
# → 404 = the projection has not caught up, or the order does not exist (indistinguishable) — retry with the same cursor; the first 404 is not a terminal state

Order & settlement states

Order state comes from GET /markets/{marketId}/orders/{orderId}; settlement state from GET /me/settlements.

Endpoint groups

• Authentication — Fetch the message to sign, exchange a signature for a token, inspect the session, log out (4 endpoints)
• Markets — Market discovery and detail (3 endpoints)
• Market Data — Quotes, order book, trades, candles (4 endpoints)
• Events — PX discovery layer: event catalog, tags, probability history and 5-minute up/down (public reads) (7 endpoints)
• PX Account — Balance, positions, orders, fills and the funding ledger (PX line, E6 strings) (6 endpoints)
• Margin & Lending — Credit state, borrow/repay, lending and liquidation records (6 endpoints)
• InfoAI — AI picks and the advisor (public reads, permanently degradable) (2 endpoints)
• Orders — Place, cancel, heartbeat, redeem (9 endpoints)
• Account — Balance snapshot (1 endpoint)
• Positions — Positions and on-chain settlement state (3 endpoints)
• WebSocket — Realtime stream handshake (1 endpoint)
• Market Maker API — batch place/cancel, kill switch, cancel-on-disconnect heartbeats, dual-bucket rate limiting (6 endpoints)
• Real-time data (WebSocket) — subscription protocol, topic dictionary, reconnect rules
• Errors — the shared error body, the two meanings of 404, and what each status code means