# HZURA Casino API

Customer integration for the casino routes on `https://api.hzura.com`.

| Area | Status |
| ---- | ------ |
| Catalog, launch, and transfer wallet HTTP contract | Implemented |
| Seamless wallet contract (HZURA calls the customer) | Implemented |
| Launch against the configured provider | Previously observed. Not re-certified in the final pass. |
| Game bets, wins, and refunds from the provider | Implemented against QTech Common Wallet v2.50. Provider certification pending. |
| Creating bonuses, jackpots, free spins, promotions | Not part of this API. Free-round bets and rewards a game reports are settled like other bets and wins. |

The machine-readable contract is [casino.openapi.yaml](casino.openapi.yaml).

Sports, events, and odds stay on the existing GET routes. This guide does not
change that contract. Casino calls need a customer API key. An IP-only client
has no customer and cannot call these routes.

Examples use placeholders. Do not put a real API key in source control.

```text
https://api.hzura.com/api/v1
```

## 1. Authenticate

Send the customer API key and call from an IP inside that customer's CIDR
allow-list.

```http
Authorization: Bearer YOUR_API_KEY
```

`X-Api-Key: YOUR_API_KEY` is equivalent. When both headers are present, the
bearer value is the key.

Casino does not accept `customer_id`, `customerId`, a provider player id, or
provider credentials. Unknown JSON fields are rejected.

A missing key, an unknown key, a disabled customer, or a CIDR miss all return
the same body:

```json
{"error":"ip_not_allowed","message":"Client address is not allowed"}
```

Casino access can also be turned off for an otherwise valid key:

```json
{"error":"casino_access_disabled","message":"Casino access is not enabled"}
```

## 2. List games

```http
GET /api/v1/casino/games
```

The list is the games this customer may see. Inactive or removed providers are
hidden. Reviewed providers are visible unless this customer has turned that
provider off. New providers stay hidden until this customer turns them on.

| Query | Rule |
| ----- | ---- |
| `provider` | Catalog provider id. Unknown ids are `invalid_provider`. Max 200 characters. |
| `category` | Catalog category id. Unknown ids are `invalid_category`. Max 200 characters. |
| `search` | Max 100 characters. |
| `page` | Integer ≥ 1. Default 1. |
| `limit` | Integer 1–100. Default 50. |
| `currency` | One of the customer's allowed currencies. Case-insensitive. Omitted means the customer's default currency, and games are filtered to that currency. |
| `language` | Games that list this language. `en-US` and `en_US` match. `en` does not match `en_US`. Max 32 characters. |
| `device` | Case-insensitive match on supported devices or client types. Max 64 characters. |

```bash
curl -sS "https://api.hzura.com/api/v1/casino/games?limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "data": [
    {
      "id": "DS-example",
      "name": "Example",
      "provider_id": "provider-1",
      "provider_name": "Provider",
      "category": "CASINO/SLOT",
      "categories": [{ "id": "SLOT", "name": "Slot" }],
      "description": null,
      "images": [],
      "supported_devices": ["desktop", "mobile"],
      "client_types": ["HTML5"],
      "supported_currencies": [{ "id": "EUR", "name": "Euro" }],
      "languages": [{ "id": "en_US", "name": "English" }],
      "demo_support": true,
      "free_round_support": false,
      "rtp": "96.5",
      "volatility": null,
      "features": [],
      "themes": [],
      "release_date": null
    }
  ],
  "pagination": { "page": 1, "limit": 1, "total": 1, "total_pages": 1 }
}
```

An empty `data` array with `total: 0` is a successful page, not an error.

## 3. Launch a game

```http
POST /api/v1/casino/games/{gameId}/launch
Content-Type: application/json
```

`{gameId}` is `data[].id` from the catalog. The body limit is 8 KiB.

```bash
curl -sS -X POST "https://api.hzura.com/api/v1/casino/games/DS-example/launch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","device":"desktop","mode":"real"}'
```

```json
{"url":"https://games.example/launch/session"}
```

The response is only `url`. It does not include tokens or the upstream body.

| Field | Rule |
| ----- | ---- |
| `player_id` | Required. The customer's player id. 1–64 characters. Starts with a letter or digit. Then letters, digits, `.`, `_`, `-`. |
| `currency` | Optional. Three letters. Must match the currency already stored for this player, or the customer's default currency when this is the first launch. |
| `language` | Optional catalog filter only. It does not choose the language sent to the provider. |
| `device` | Optional. `desktop` or `mobile`. When omitted, `desktop` is used if the game lists desktop or lists no device. Otherwise `mobile` is used when the game lists it. |
| `mode` | Optional. `real` (default) or `demo`. `demo` requires `demo_support: true`. |
| `display_name` | Optional. Name shown to the player in the game. At most 50 characters, no control characters. Not stored. |

Country and currency are taken from the customer's casino configuration, then
stored on the player. A later launch cannot switch them. The return URL is
server configuration. Sending `return_url` or `returnUrl` is `invalid_launch`.

The launch language is the locale stored on the player: the customer's
configured locale, or the server locale when the customer has none. `en-US`
and `en_US` are the same locale and are sent as `en_US`. A two-letter code
such as `en` is not a launch language. If no `ll_RR` locale can be resolved,
the launch is rejected and a new player is not created.

A `real` launch opens a game session for the player that lasts 6 hours. Bets
need a live session. Wins and refunds for a round that started in time still
settle after it ends. `demo` opens no session and never touches a wallet. A
seamless customer without a wallet URL and signing secret cannot launch in
real mode (`503 wallet_not_configured`).

## 4. Players

There is no separate create-player route. The first launch that passes
validation stores `player_id` for this customer. Later launches and every
wallet call reuse that id.

The same `player_id` at another customer is a different player. One customer
cannot read or move another customer's player.

The wallet does not create a player. Call launch before using the transfer
wallet. A launch that fails after the player row is stored still leaves that
mapping in place. Repeat the launch with the same `player_id`.

## 5. Wallet modes

HZURA sets one wallet mode per customer.

| Mode | Who holds the balance | What you build |
| ---- | --------------------- | -------------- |
| Transfer | HZURA, one casino balance per player | Fund and withdraw with `POST /api/v1/casino/wallet` (sections 6 to 10). Bets and wins settle on that balance without a call to you. |
| Seamless | You | One HTTPS endpoint that HZURA calls for every balance read, bet, win, and refund (section 11). The transfer route returns `409 wallet_mode_mismatch`. |

A customer moves from transfer to seamless only after every HZURA casino
balance of its players is withdrawn.

## 6. Transfer wallet

```http
POST /api/v1/casino/wallet
Content-Type: application/json
```

`CREDIT` funds the player's casino balance. `DEBIT` withdraws from it back to
you. `ROLLBACK` reverses one of your own `DEBIT` or `CREDIT` calls. `BALANCE`
reads it. Each call is one database transaction. No game provider is called,
so a call either completes or is refused. There is no pending state.

When casino access is turned off, `CREDIT` is refused with
`casino_access_disabled`. `BALANCE`, `DEBIT`, and `ROLLBACK` keep working so
the remaining balance can be withdrawn.

```bash
curl -sS -X POST "https://api.hzura.com/api/v1/casino/wallet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","operation":"BALANCE"}'
```

```json
{
  "operation": "BALANCE",
  "status": "success",
  "currency": "EUR",
  "balance": "0"
}
```

The balance includes every bet and win settled so far. The first read creates
the wallet at zero if the player exists and has none yet.

`currency`, when sent, must be three uppercase letters equal to the player's
currency. `EUR` matches a EUR player. `eur` is `invalid_wallet`. A different
currency is `unsupported_currency`.

## 7. Credit (fund)

```bash
curl -sS -X POST "https://api.hzura.com/api/v1/casino/wallet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","operation":"CREDIT","transaction_id":"deposit-1001","amount":"12.50","currency":"EUR"}'
```

```json
{
  "operation": "CREDIT",
  "status": "success",
  "currency": "EUR",
  "balance": "12.5",
  "transaction_id": "deposit-1001"
}
```

`amount` is required and must be greater than zero. Send it as a decimal
string. A JSON number is accepted. Signs, exponents (`1e2`), and more than
eight fractional digits are rejected.

## 8. Debit (withdraw)

```bash
curl -sS -X POST "https://api.hzura.com/api/v1/casino/wallet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","operation":"DEBIT","transaction_id":"withdraw-1001","amount":"5.00","currency":"EUR"}'
```

```json
{
  "operation": "DEBIT",
  "status": "success",
  "currency": "EUR",
  "balance": "7.5",
  "transaction_id": "withdraw-1001"
}
```

The balance cannot go below zero:

```json
{"error":"insufficient_balance","message":"Wallet balance is not sufficient"}
```

That refusal is final for this `transaction_id`.

## 9. Rollback

Rollback reverses one of your successful `DEBIT` or `CREDIT` calls for the
same player, currency, and amount.

```bash
curl -sS -X POST "https://api.hzura.com/api/v1/casino/wallet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","operation":"ROLLBACK","transaction_id":"rb-1001","reference_transaction_id":"withdraw-1001","amount":"5.00","currency":"EUR"}'
```

```json
{
  "operation": "ROLLBACK",
  "status": "success",
  "currency": "EUR",
  "balance": "12.5",
  "transaction_id": "rb-1001"
}
```

`transaction_id` is the rollback's own idempotency key.
`reference_transaction_id` is the original debit or credit. The amount must
equal the original amount.

Rolling back a debit returns the amount. Rolling back a credit takes it out
again; if the player has already played part of it, the response is
`insufficient_balance`. A second rollback of the same original is
`wallet_already_rolled_back`. Failed originals cannot be rolled back
(`wallet_transaction_not_reversible`). An unknown reference is
`wallet_transaction_not_found`. Game bets and wins are not reachable here.

## 10. Idempotency

`transaction_id` is unique per customer, including across players.

| Repeat | Result |
| ------ | ------ |
| Same key, same player, operation, amount, and currency | Original result. Money moves once. |
| Same key, different body | `409 wallet_idempotency_conflict` |
| Same key after a refusal | The original error, such as `insufficient_balance`. |

After a network error or a `503`, repeat the call with the same
`transaction_id`. `wallet_transaction_pending` and `wallet_provider_failed`
only appear when a key from the earlier provider-backed wallet is repeated.

## 11. Seamless wallet

You keep the balance. HZURA sends one JSON `POST` to the HTTPS URL you give us
for every balance read, bet, win, and refund. Answer within 3.5 seconds (1
second to connect). Redirects are not followed. A response over 16 KiB counts
as no answer.

| Header | Value |
| ------ | ----- |
| `Content-Type` | `application/json` |
| `X-Hzura-Timestamp` | Unix seconds |
| `X-Hzura-Signature` | Lowercase hex HMAC-SHA256 of `{X-Hzura-Timestamp}.{raw body}`, keyed with your signing secret |

Reject a request whose signature does not match. Every attempt is signed
again, so a repeated `transaction_id` carries a new timestamp.

| Field | Sent on | Meaning |
| ----- | ------- | ------- |
| `operation` | Always | `BALANCE`, `DEBIT`, `CREDIT`, or `ROLLBACK` |
| `player_id` | Always | Your player id from launch |
| `currency` | Always | Player currency |
| `transaction_id` | `DEBIT`, `CREDIT`, `ROLLBACK` | Your idempotency key for this movement |
| `reference_transaction_id` | `ROLLBACK` | The `DEBIT` to refund |
| `amount` | `DEBIT`, `CREDIT`, `ROLLBACK` | Decimal string. Two decimals for fiat, up to eight for BTC, ETH, XRP, LTC, BCH, BNB, BUSD. `"0.00"` is possible on a free-round debit or a losing credit. |
| `reason` | `DEBIT`, `CREDIT`, `ROLLBACK` | `BET`, `WIN`, `REWARD`, or `REFUND` |
| `round_id`, `game_id`, `round_completed` | When known | Round context |
| `bonus` | Bonus rounds | `{type, promo_code?, bet_amount?}`, `type` is `FREE_ROUND` or `FEATURE_TRIGGER` |

```json
{
  "operation": "DEBIT",
  "player_id": "player-1",
  "currency": "EUR",
  "transaction_id": "7316495845",
  "amount": "10.00",
  "reason": "BET",
  "round_id": "1nnrtsy56",
  "game_id": "TK-froggrog",
  "round_completed": false
}
```

Success is `200` with the balance after the operation and, optionally, your
own reference (1–128 letters, digits, `-`, `_`, `.`, `:`):

```json
{"balance":"90.00","transaction_id":"your-ledger-id-1"}
```

To refuse, answer `4xx` with `{"error": "...", "message": "..."}`:

| `error` | Use it when |
| ------- | ----------- |
| `insufficient_balance` | The balance cannot cover the bet |
| `player_blocked` | The player may not play |
| `player_not_found` | You do not know `player_id` |
| `invalid_request` | The request cannot be applied, including a `DEBIT` already cancelled by a `ROLLBACK` |

Rules:

- A refused `DEBIT` is final; HZURA answers repeats itself.
- Do not refuse a `CREDIT` or `ROLLBACK`. A refusal counts as no answer and the
  game provider sends it again.
- No answer in time, a `5xx`, a redirect, an unknown `error`, or an unreadable
  body: HZURA stores nothing, and the provider repeats the `transaction_id` or
  sends a `ROLLBACK`.
- Apply each `transaction_id` once. On a repeat, answer `200` with the balance
  and the same `transaction_id` as the first time.
- A `ROLLBACK` for a debit you never applied, or already refunded, is `200`
  with the balance and moves no money.
- A `ROLLBACK` can arrive before its `DEBIT`. If that `DEBIT` arrives later,
  refuse it with `invalid_request`.
- Apply a `CREDIT` or `ROLLBACK` even after the session ended or the player was
  blocked.

## 12. Currency, language, and device

| Topic | Rule |
| ----- | ---- |
| Player currency | Customer's default casino currency, which must be on the allow-list. Fixed on first launch. |
| Wallet currency | The player's currency. Optional request currency must be three uppercase letters and equal to it. |
| Catalog currency | Case-insensitive allow-list check. Omitted uses the default currency as a filter. |
| Launch language | Stored player locale in `ll_RR` form. Request `language` only filters the catalog. |
| Device | `desktop` or `mobile` on launch. The games query matches catalog device text and is not limited to those two words. |
| Mode | `real` or `demo`. |

## 13. Errors

Every error body is:

```json
{"error":"game_not_found","message":"Game not found"}
```

Messages are static. They do not include keys, tokens, SQL, or upstream bodies.

| HTTP | `error` | When |
| ---- | ------- | ---- |
| 400 | `invalid_query` | A games filter is empty or too long |
| 400 | `invalid_page` | `page` is not a positive integer |
| 400 | `invalid_limit` | `limit` is outside 1–100 |
| 400 | `unsupported_currency` | Currency is not allowed, or it does not match the player |
| 400 | `invalid_provider` | Provider filter is not in the catalog |
| 400 | `invalid_category` | Category filter is not in the catalog |
| 400 | `invalid_launch` | Launch body, game id, `display_name`, or content type is not usable |
| 400 | `invalid_wallet` | Wallet body or amount is not usable |
| 400 | `player_not_configured` | Country, currency, or launch locale is not configured |
| 403 | `ip_not_allowed` | Key or IP was not admitted, including a casino call with no customer |
| 403 | `casino_access_disabled` | Casino is off for this customer (on the transfer wallet: `CREDIT` only) |
| 403 | `game_not_available` | The game exists but is not launchable for this request |
| 404 | `game_not_found` | Game id is not in the catalog |
| 404 | `player_not_found` | No player mapping for this customer and `player_id` |
| 404 | `wallet_transaction_not_found` | Rollback reference is unknown for this customer |
| 409 | `insufficient_balance` | Debit or credit-rollback would go below zero |
| 409 | `wallet_mode_mismatch` | This customer uses the seamless wallet |
| 409 | `wallet_idempotency_conflict` | Same `transaction_id`, different request |
| 409 | `wallet_transaction_pending` | Key from the earlier provider-backed wallet, still pending |
| 409 | `wallet_already_rolled_back` | The original transaction was already reversed |
| 409 | `wallet_transaction_not_reversible` | Failed, or otherwise not reversible |
| 413 | `payload_too_large` | Launch or wallet body is over 8 KiB |
| 502 | `launch_authentication_failed` | Provider authentication failed |
| 502 | `launch_failed` | Provider rejected the launch |
| 502 | `wallet_provider_failed` | Key from the earlier provider-backed wallet that the provider rejected |
| 503 | `casino_catalog_unavailable` | Catalog is not available |
| 503 | `launch_not_configured` | Launch is not configured on this process |
| 503 | `player_store_unavailable` | Player store could not be used |
| 503 | `wallet_not_configured` | Wallet is not configured, or a seamless customer has no wallet URL or secret |
| 503 | `wallet_store_unavailable` | Wallet or game-session store could not be used |
| 503 | `redis_unavailable` | Catalog store could not be read |
| 504 | `launch_unavailable` | Launch provider did not answer |
| 504 | `redis_timeout` | Catalog store timed out |

`not_found` is an unknown URL. `method_not_allowed` is the wrong HTTP method.
Both use the same JSON shape.

## 14. Retries

| Response | What to do |
| -------- | ---------- |
| 429 | Casino routes are not rate limited. This status is not produced for `/api/v1/casino/*`. |
| 409 `wallet_mode_mismatch` | You are on the seamless wallet. Answer HZURA's calls instead. |
| 409 `wallet_transaction_pending` or 502 `wallet_provider_failed` | Only for keys from the earlier provider-backed wallet. Contact HZURA. |
| 504 `launch_unavailable` | Safe to retry the same launch. Launch does not move the wallet. |
| 503 catalog or store errors | Retry later with the same request. Wallet calls are idempotent. |
| 409 `insufficient_balance` | Do not retry until the balance can cover the amount. |
| 409 `wallet_idempotency_conflict` | Do not change the body under that `transaction_id`. |
| 400 | Fix the request. Do not retry it unchanged. |
