Settlement

curl -s "$PREDICTA_BASE/api/v1/settlements?externalUserId=user-4471&outcome=won&limit=100" \
  -H "Authorization: Bearer $PREDICTA_KEY"

{
  "settlements": [
    {
      "id": "stl_…",                  // stable. Safe as the idempotency key for a credit.
      "positionId": "pos_…",
      "externalUserId": "user-4471",  // YOUR id, never a Predicta uuid
      "side": "YES",
      "resolution": "YES",            // YES | NO | VOID, as resolved upstream
      "outcome": "won",               // won | lost | void, for this position
      "contracts": 68.6111,
      "realisedPnl": 18.61,           // THIS settlement's
      "lifetimeRealisedPnl": 18.61,   // the position's running total
      "settledAt": "2026-08-21T18:02:11.004Z",
      "operatorMoney": {
        "currency": "USD",
        "settlementCredit": "68.61",  // CREDIT THIS
        "voidCredit": "0.00"
      },
      "cursor": "…"
    }
  ],
  "nextCursor": "…",
  "hasMore": false
}

Exactly one credit is non-zero

A void refunds the commission as well as the stake. Predicta did not provide the market, so it does not keep the fee: quietly retaining it would be a new commercial term introduced by a backend decision. The two fields are separate rather than one signed amount because a refund and a win are different postings in an operator's books.

A contract settles at exactly $1.00 or exactly $0.00. There is no third case: a market that resolved 99% certain did not resolve.

• Key your credit on the settlement's id — it is stable and it is what makes re-processing a no-op. positionId works equally well and is what the webhook keys on, so a partner using both never processes the same fact twice.
• Advance your stored cursor only after the batch is applied. Reading does not consume: the same cursor returns the same page, so a consumer that crashes mid-batch re-reads rather than skips.
• The register is scoped to your operator inside the query, not filtered afterwards. Another partner's settlements are not reachable by guessing a cursor.
• hasMore: false means caught up. Poll on the order of once a minute; settlements are not high-frequency events.

for await (const s of predicta.iterateSettlements({ settledFrom: lastRun })) {
  // s.operatorMoney.settlementCredit and .voidCredit are exact Decimal strings.
  await ledger.creditOnce(s.id, s.externalUserId, s.operatorMoney);
}

It pages on settledAt with no tiebreaker — and settlements written in one transaction share a timestamp exactly — so it can drop or repeat rows at a page boundary. It is left working rather than removed because it is already a published contract, but new integrations should use the register above: same records, keyset cursor on a monotonic sequence, no gap.

Three layers, each of which would be sufficient alone:

• The position row is locked for update inside the settlement transaction, so two concurrent sweeps serialise rather than both reading it as open.
• Only a position still marked open is considered.
• The settlement insert carries a unique index on positionId. If it inserts nothing, no credit is computed, no status is written and no event is emitted.

The third is the one that holds if the others are ever wrong, because it is a database constraint rather than a branch in application code.

Upstream sources sometimes change a published result. Predicta handles that by refusing to pretend it did not happen, and by refusing to act unilaterally.

The register answers “what settled”. To check that every money fact of a period agrees — trial balance, cash statement, venue agreement, and the individual findings when it does not — read Reconciliation. Its feed carries position.settled alongside every fill, fee and collateral movement, totally ordered and resumable, which is the stream to build a nightly close on.

GET /api/settlements is unauthenticated and publishes market outcomes: one row per resolved contract, with no reference to who held what. It is the right feed only if you run your own book against Predicta's resolutions. If Predicta recorded the positions, use the register above — working out who held what from a market outcome is precisely the arithmetic that must not be performed in two places.