Mutation semantics

HTTP acceptance only

Mutations such as placeBet, sellBet, createDuel, pack picks, and tournament enters return HTTP 2xx acceptance — not guaranteed on-chain finality.

The backend may still validate, queue, or submit transactions asynchronously.

Reconciliation strategies

1. Poll reads — getUserShares, parlay.getStatus, tournament detail
2. waitFor* helpers — waitForParlaySettlement, waitForTournamentEntry
3. Realtime — sdk.realtime.subscribeToDuel, market list websocket
4. Ably — subscribeTournamentAblyChat for tournament chat (not bet finality)

There is no universal waitForFinality() yet — the backend does not expose a mutation-status API for all writes.

Idempotency

Pass idempotencyKey on supported mutations:

await sdk.user.placeBet(body, { idempotencyKey: 'bet-unique-id' });

The SDK sends x-idempotency-key automatically when configured.

On-chain mutations

When using sdk.onchain, the SDK sends transactions via your viem wallet. Wait for receipt, then confirm with HTTP reads:

const { hash } = await sdk.onchain!.placeParlayFromQuoteId(quoteId);
await waitForParlaySettlement(sdk.tournaments!.parlay, parlayId);

Errors

Use isBentoSdkError and isGeoblockError for typed error handling.