Copy page

Trading

Order Lifecycle and Settlement

An order lifecycle does not end when an order is accepted. A reliable prediction-market integration follows the order from submission through fills, position updates, contract resolution, and settlement.

The lifecycle

Code
Discover a contract
      ↓
Place an order
      ↓
Observe order events and fills
      ↓
Reconcile open orders and positions
      ↓
Wait for contract resolution
      ↓
Read settled positions and payout

1. Discover the contract

Start with an active event and select the contract you want to trade. Use the exact instrumentSymbol returned by the API for WebSocket subscriptions and order requests.

• List events
• Get an event
• Prediction Markets ticker overview

Do not construct a tradable symbol from a display name or assume that a ticker format applies to every market type.

2. Place and manage the order

Before placing an order, confirm that the account has the required role or OAuth scope and has accepted the current Prediction Markets terms.

• Check terms status
• Place an order
• Cancel an order
• Place batch orders
• Cancel batch orders

REST order placement is useful for one-off or server workflows. For active trading and market making, the documented WebSocket order.place flow is preferred. REST and WebSocket payloads are not interchangeable; follow the interface-specific reference for field names, casing, and permissions.

3. Monitor accepted orders and fills

Use authenticated WebSocket order events for live order and fill state. The public trade stream reports market-wide executions, not the authenticated account's fills. Keep local order state keyed by the server order identifier and treat messages as events that may need deduplication or replay protection.

After startup, reconnects, or any detected message gap, use REST to rebuild state:

• Get active orders
• Get order history
• Prediction Markets WebSocket streams

An order being accepted does not mean it has filled. Reconcile open quantity, executed quantity, and fills before updating available strategy capacity.

4. Reconcile positions

After fills, query positions to confirm the account-level result. Use WebSocket position and balance updates for responsiveness, then use REST as the recovery and audit snapshot.

• Get open positions
• Get settled positions
• Get volume metrics

Keep order state and position state separate. A canceled order can leave a filled position, and a partially filled order can leave both remaining open quantity and an updated position.

5. Handle resolution and settlement

Resolution determines which outcome is correct for the event. After the contract settles, use the settled-positions response as the authoritative historical record for the position, payout, and resolution side.

Do not infer settlement from an event end time alone. Follow the contract status and the documented settled-position response, and preserve the event, contract, order, fill, and position identifiers needed for reconciliation.

Reliability checklist

• Persist order, fill, position, event, and contract identifiers.
• Use the exact instrumentSymbol returned by the API.
• Treat WebSocket updates as the low-latency path and REST snapshots as the recovery path.
• Reconcile after reconnects, timeouts, rejected messages, and suspected gaps.
• Track partial fills separately from remaining open quantity.
• Confirm settlement through the settled-positions endpoint before closing accounting records.

Next steps

• Trading Quickstart
• Market Data
• Order Management REST API