Orders, fills and portfolio
Build around durable commands and confirmed fills, not HTTP acceptance.
Discover and validate
Use /v1/events, /v1/markets, /v1/markets/{conditionId} and
/v1/books/{tokenId} to select a real market/outcome. Read /v1/order-requirements
and /v1/trading-status; retain tick size, minimum and service restrictions.
Requirements needs tokenId and BUY/SELL side; type defaults to market.
Optional amount, comma-separated amounts (up to six), price and size
must be positive. Limit BUY requirements needs price between zero and one.
Do not hardcode an outcome token, market ID or execution host from an example.
Submit an order
POST /v1/accounts/{externalUserId}/orders
Idempotency-Key: order-intent-unique-001{
"marketId": "actual-market-id",
"tokenId": "12345678901234567890",
"side": "BUY",
"type": "limit",
"price": "0.62",
"size": "10"
}The token above is illustrative. Common fields: marketId, tokenId, side
(BUY/SELL), type (market/limit), amount, price, size, priceLimit,
orderType, expiresInSeconds, outcomeIndex, tickSize, negRisk.
Use valid combinations and market precision. Keep monetary input as decimal
strings; do not round-trip token base units through JavaScript floating point.
Market BUY amount is a cash budget; configured fees affect executable notional.
Market SELL amount is shares, not dollars. Limit price is cash per share and
size is shares. CRISP validates current fees, exposure and funds at execution.
An optional priceLimit caps/floors market execution; without it the executor
derives a protected limit from a fresh book. This is not a fill guarantee.
Acceptance and recovery
202 returns data.command (id/state/failureCode) and data.order (including
id when known, status and optional fill). Queued/running is pending. Succeeded
means the command succeeded; an accepted limit order can still be open/unfilled.
Failed and ambiguous responses require different treatment.
For pending order/cancel/redemption commands, re-send the same original path,
key and body with fresh HMAC headers and bounded backoff. This resumes the
existing durable intent; never create a replacement intent after an uncertain
timeout. There is no general public partner /commands/{id} endpoint in the
current catalogue. Use lifecycle events and resource reads for final state.
Optional POST /orders/prewarm accepts { "tokenIds": ["…"] } (one or two).
Debounce it and never block trading on it. Optional order-cell capability is
server-only and deployment-dependent; coordinate with CRISP before using the
returned endpoint/capability. Ordinary /orders is sufficient for integration.
Portfolio and history
Endpoint suffix after /v1/accounts/{externalUserId} | Purpose |
|---|---|
/orders | Open orders; not complete fill history |
/orders/{orderId}/cancel (POST) | Durable cancel, idempotency required |
/positions | Current position data; closed, limit/offset supported |
/sellable-shares?tokenId=… | Returns tokenId, availableShares and asOf for a ready account |
/trades | Account wallet trade data |
/trade-fills | Canonical partner fills with fee-distribution metadata |
/orders/{orderId}/trade-fills | One order's individual confirmed fills |
For /trade-fills, from and to ISO timestamps are required (ascending window
up to 366 days). Default limit 50, maximum 100; persist cursor and use hasMore.
For one order's fills, limit defaults to 100, maximum 200. Older history remains
reachable through earlier windows; a window bound is not ledger expiry.
Volume means confirmed USD fill notional, not shares. Do not sum accepted orders
and confirmed fills together or confuse venue fees with referral allocations.
Redeem resolved positions
POST /v1/accounts/{externalUserId}/positions/redeem
Idempotency-Key: redeem-intent-unique-001{
"positions": [{
"conditionId": "0x…",
"size": 7.77,
"outcomeIndex": 0,
"negRisk": false
}]
}Use live position tuples, not the placeholder. 1–20 distinct condition IDs; eligibility/outcome/size are revalidated before signing. Show a confirmation: close losing positions for zero or claim winning payout. 202 is pending; update portfolio only after confirmation/reconciliation. Allowed in cancel-only mode, blocked when trading is disabled.