Orders

1. 1Quote→
2. 2Confirm→
3. 3Order→
4. 4Route→
5. 5Fill→
6. 6Position

Confirmation is an input to this pipeline, never a shortcut around it. The order row is written before anything is sent, because an execution that succeeds upstream and then fails to be recorded is the one outcome with no recovery path.

accepted → submitted → filled | partially_filled | rejected
              └→ unknown after timeout → 409 reconciliation_required

settlementState collapses six statuses to the only question a wallet has to answer right now: is the money final, or must I hold and come back? Switch on it, and submitted can never be mistaken for terminal.

{
  "quoteId": "fc3be731-98dc-4c03-80ac-23576a708d9c",
  "clientOrderId": "ticket-9031"    // YOUR id. The idempotency key.
}

{
  "orderId": "3dd27f36-7780-4aa7-8af2-1a6854fbf8cb",
  "clientOrderId": "ticket-9031",
  "status": "filled",
  "contractId": "ctr_9f31c2…",
  "side": "YES",
  "action": "buy",
  "filledQuantity": 68.6111,
  "averagePrice": 0.72,
  "predictaFee": 0.6,
  "predictaFeeBps": 120,
  "notional": 49.4,
  "stake": 50,
  "rejectReason": null,
  "simulated": true,
  "createdAt": "2026-08-20T04:43:40.282Z",
  "idempotentReplay": false,
  "routing": { "reason": "only_venue", "consideredVenues": 1 },

  "operatorMoney": {
    "currency": "USD",
    "authorizationAmount": "50.00",   // what you reserved
    "actualDebit": "50.00",           // TAKE THIS
    "releaseAmount": "0.00",          // GIVE THIS BACK
    "tradeAmount": "49.40",
    "platformFee": "0.60",
    "venueFee": "0.00",
    "venueFeeKnown": true
  },
  "operatorExitMoney": null
}

A sell is a credit, and carries a different object

On an exit operatorMoney is null — deliberately — and operatorExitMoney.sellProceeds is what to credit, already net of the platformFee and venueFee reported beside it. A single object for both directions would hand a wallet an authorizationAmount on a trade that pays cash out, and a partner applying the contract as written would debit the player for selling their own position.

clientOrderId is unique per operator and player, enforced by a database index rather than by a check in application code. Two requests arriving together produce one order; the loser of the race re-reads the winner's.

• Derive the key from the reservation in your own ledger. A random value per attempt gives you no protection at all, because a retry has to present the same string. A clock gives you a key you cannot reproduce after a crash.
• A rejected order still consumes its key. Retrying a spent key after a rejection must not open a second live order, so the rejected record stays.

# 1. You have an orderId — poll it.
GET /api/v1/orders/{orderId}
→ { "status": "submitted", "settlementState": "pending",
    "operatorMoney": { "actualDebit": "0.00", "releaseAmount": "50.00", … } }

# 2. You never received a response at all — look it up by YOUR id.
GET /api/v1/orders?externalUserId=user-4471&clientOrderId=ticket-9031
→ { "orders": [ … ], "count": 1, "nextCursor": null }

• clientOrderId is the identifier that survives a crash mid-request: you chose it before the request was sent. Predicta's orderId only ever existed in a response you may not have received.
• It is unique within a user, so it must be sent with externalUserId. Alone it is 400 invalid_request — a question with no single answer, and returning the first match would silently pick one.
• The lookup is a filter on the list route rather than a second endpoint, so a reconciler uses one call for “this one order” and “everything since 09:00”.
• While unresolved, the read reports actualDebit of "0.00" with the whole authorization as releaseAmount. That is a description of an unfinished order, not an instruction to release: settlementState is what tells you whether to act.

import { ReconciliationRequiredError } from '@predicta/sdk';

try {
  const order = await player.submitOrder({ quoteId, clientOrderId: 'ticket-9031' });
  ledger.settle(order.operatorMoney);
} catch (err) {
  if (err instanceof ReconciliationRequiredError) {
    // err.holdAuthorization === true
    const found = await player.findOrderByClientOrderId('ticket-9031');
    if (found?.settlementState === 'pending') return schedulePoll();
  }
  throw err;
}

Paging is keyset for the same reason as the catalogue: orders arrive while you page, and an offset would let one placed between two requests push an older order across the page boundary where you never see it — a missing trade, reported as a successful page.

• Every order leaves the API through the same serialiser the POST response uses. A stored POST response and a later GET describe the order identically — the fields most likely to differ between two shapes are exactly the ones that decide money.
• An order belonging to another partner returns the same 404 unknown_order as one that does not exist. Distinguishing them would make the route an oracle for whether a guessed id is real.

Why fills are nested under an order

There is no top-level fills feed, and that is deliberate. A fill carries no money contract of its own: operatorMoney belongs to the order, computed once over the whole execution. A partner booking per fill double-counts the moment a venue fills one order in two pieces. Fills are a reconciliation detail — fillId, quantity, price, filledAt — and are off by default because the order already carries the average price, the filled quantity and the money.

The quoted price is a ceiling. If the book has moved past it by the time the order is submitted, the order is rejected rather than filled: the player agreed to a number, and a fill at a worse one is not the trade they confirmed.

A filled order opens or extends a position, readable at GET /api/v1/positions and GET /api/v1/positions/{id}. A position carries operatorMoney.costBasis and operatorMoney.realisedPnl, which are facts, not instructions — cash already debited, and P&L already booked. There is no mark-to-market: a number that moves on its own is not something a ledger can reconcile against, and a partner who wants the mark quotes a sell.

Every money fact an order produces also lands on the reconciliation feed — order.state_changed, order.filled, fee.assessed, collateral.moved — totally ordered and resumable. See Reconciliation.