> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.wuzzlo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.wuzzlo.com/_mcp/server.

# Settlement and recovery

# Settlement and recovery

Automatic settlement is initiated by Wuzzlo. The operator does not poll the game or calculate winners. Wuzzlo determines the result and sends a signed `POST /resultrequest` callback to the configured operator credit path.

## Normal lifecycle

```text
OPEN
  ├─ betrequest succeeds ──> DEBITED
  │                           ├─ resultrequest ──> SETTLED
  │                           └─ rollbackrequest ─> ROLLED_BACK
  └─ betrequest rejected ──> no wallet transaction
```

`SETTLED` and `ROLLED_BACK` are terminal for the original debit. A callback that conflicts with a terminal state must return the documented lifecycle error and must not change balance.

## Automatic settlement behavior

1. The game engine closes or resolves a wager.
2. Wuzzlo creates the wallet settlement operation with stable identifiers.
3. Wuzzlo sends the signed result callback.
4. The operator verifies, applies, and durably records the result in one transaction.
5. If delivery fails or its outcome is uncertain, Wuzzlo may retry. The same identifiers make the retry safe.
6. Background recovery can redeliver pending wallet operations. Therefore idempotency must survive process restarts and long delays.

Some games settle on an explicit cashout; others settle when a round closes or through a server-side safety worker. This difference is internal to Wuzzlo. The operator handles every result through the same signed, idempotent wallet contract.

## Retry rules

* An exact request replay uses the same `reqId` and must not repeat the mutation.
* A repeated logical transaction with a new `reqId` must follow the transaction lifecycle status for that endpoint.
* Do not expire idempotency records after a short in-memory replay window. Retain them according to the financial record-retention agreement.
* Do not create a new transaction identifier merely because an HTTP request timed out.

## Ambiguous outcomes

An outcome is ambiguous when a caller cannot know whether the remote side committed—for example, a timeout after sending a request. Do not assume failure.

Operators can query:

* `POST /api/operator/get-bet-info` for Wuzzlo's view of one transaction.
* `POST /api/operator/get-market-result` for aggregate and item-level round reconciliation.

These endpoints are signed, read-only evidence. They do not replace the operator's durable callback handling and must not themselves create a second settlement.

## Reconciliation job

Run a scheduled job that finds old `DEBITED`, locally pending, or ambiguous records and compares them with Wuzzlo. Correlate by `operatorId`, `transactionId`, `roundId`, and `gameId`. Escalate disagreements instead of silently adjusting balances.

For a round, compare `totalBets`, `settledBets`, `openBets`, `totalStake`, and `totalPayout` before comparing individual items.

## Operational monitoring

Alert on:

* callbacks that remain pending after retries;
* signature failures or unexpected source networks;
* repeated lifecycle conflicts;
* balance or currency mismatches;
* growing unsettled transaction age;
* reconciliation differences;
* elevated callback latency or HTTP failures.

Never include private keys, full session tokens, or sensitive player data in logs. Preserve request hashes and correlation identifiers for auditability.