# Operator wallet contract

OneHazel connects game studios to your wallet. Each studio speaks its own wallet protocol, and OneHazel translates every one of them into one contract that you implement once. You stay the system of record for player balances; OneHazel never holds player funds.

**Machine-readable spec:** [operator-wallet.openapi.yaml](/specs/operator-wallet.openapi.yaml) (OpenAPI 3.1, no key needed).

## The endpoints you implement

OneHazel calls these on your host, under the base path `/provider/v1`. Every call is an HTTPS `POST` with a JSON body.

| Endpoint | Purpose |
|---|---|
| `/session/start` | Mint a single-use launch token for a player and game |
| `/session/exchange` | Exchange a launch token for a session token and return the player view |
| `/session/balance` | Return the player's current balance |
| `/wallet/bet` | Debit a stake |
| `/wallet/win` | Credit a win |
| `/wallet/rollback` | Reverse an earlier bet or win |

## Authentication

Every call carries `Authorization: Bearer <integration key>`. You issue the key; OneHazel stores it encrypted against the connection. There is no request-body signature on these calls, so integrity relies on TLS and the key. OneHazel can send the calls from a fixed egress address so you can allowlist it.

## Money

Every amount and balance is an **integer number of minor units** of the player's currency: `1050` is 10.50 in a two-decimal currency. OneHazel converts each studio's own money format to minor units before calling you, so you never see a decimal amount.

## Idempotency and replay

Every mutating call carries an `idempotency_key`:

- Keys are opaque, unique across bets, wins and rollbacks, and stable across a studio's retries of the same transaction.
- A rollback has its own key and names the transaction it reverses in `target_idempotency_key`.
- When a key has already been processed, do not move money again. Return the original result with `duplicate: true`.
- That same rule is what makes two simultaneous copies of one transaction safe: the second one sees the first and answers `duplicate: true`.

## Wallet responses

A wallet call returns the balance after the call and a `status`:

| `status` | Meaning |
|---|---|
| `accepted` | The bet or win was applied |
| `insufficient_funds` | The stake exceeds the balance; nothing moved (HTTP 402 is also read this way) |
| `rolled_back` | The rollback was applied |

A replay keeps the original status and adds `duplicate: true`. OneHazel reads a response in this order: `duplicate`, then insufficient funds, then `accepted` or `rolled_back` with an HTTP status below 400. Anything else counts as a failed call.

Errors use `{ "success": false, "error": { "code": "...", "message": "..." } }`. OneHazel branches on `error.code`, not on the HTTP status alone, because one status can carry different meanings:

| Code | HTTP | When |
|---|---|---|
| `AUTH_INVALID` | 401 | The integration key is wrong |
| `launch_token_unknown` | 401 | The launch token was never issued |
| `launch_token_expired` | 401 | The launch token passed its lifetime |
| `launch_token_consumed` | 409 | The launch token was already exchanged |
| `session_unknown` | 401 | The session token is not recognised |
| `session_expired` | 401 | The session token has expired |

## Behaviour worth knowing

- **No zero-amount wins.** A losing spin's empty win or a round-close acknowledgement is recorded on the OneHazel side and acknowledged to the studio without calling you, so you may reject `amount_minor: 0`.
- **Free-round stakes are not debited.** A free-round bet never reaches `/wallet/bet`; a win from a free round arrives as a normal `/wallet/win`.
- **Rollback carries the original amount.** Studios often omit the amount on a cancel, so OneHazel looks it up and forwards it as `metadata.amount_minor`. Derive the direction from the target: a reversed bet is a credit, a reversed win is a debit.
- **Rounds.** `round_external_id` is the studio's round id; where a studio has no round concept, OneHazel uses the transaction id. `round_closed: true` on a win marks the round as finished.

## Known limitations today

- **Two-decimal currencies only.** Zero- and three-decimal currencies are rejected rather than converted.
- **No unified launch endpoint.** Each studio is launched through its own route today; there is no single OneHazel launch call that covers every studio.
- **Demo mode on one studio only.** Play without a real wallet session is available for one studio, not across the catalogue.
- **Jackpot data is not forwarded.** Jackpot contributions and jackpot-win flags that a studio reports are not passed through to your wallet; you receive only the stake and the win amount.
- **Free-round issuance on one studio only.** Issuing free rounds through OneHazel is supported for one studio. For the others, free-round play is handled as described above, but you cannot issue grants through OneHazel.