Casino API

You never send an account id: your API key already says who you are. Send only the documented JSON fields; any other field is refused. Launch and wallet requests can be at most 8 KiB.

This API does not create bonuses, jackpots, free spins or promotions. When a game gives a free round or a prize, it is paid like any other bet or win. There is no route to look up a single transaction later.

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

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","currency":"EUR","device":"desktop","mode":"real","display_name":"Alex"}'

{
  "player_id": "player-1",
  "currency": "EUR",
  "language": "en-US",
  "device": "desktop",
  "mode": "real",
  "display_name": "Alex"
}

Language: the game opens in your account's language, set up with HZURA (or HZURA's default if you have none). language in the body is only a check that the game has that language, like the games list filter. en-US and en_US mean the same; a two-letter code like en is not enough.

Device: without device, the game opens for desktop when it supports desktop (or lists no device), otherwise for mobile. If it supports neither, you get game_not_available.

Country and currency: on the first launch the player gets your account's country and main currency. They stay the same for that player from then on.

There is no separate "create player" step. The first successful launch registers your player_id. Every later launch and wallet request uses that same id.

Your players are yours only. The same player_id in another account is a different player, and no one else can see or move your players' money.

The wallet does not register players. Launch a game for a player before using the transfer wallet for them. If a launch fails after the player was registered, just launch again with the same player_id.

On the seamless wallet, HZURA always sends your own player_id to your wallet.

Your account uses one wallet type, chosen with HZURA. All of your players use it for every game.

To switch from transfer to seamless, every player's casino balance must first be taken out. The seamless wallet needs your wallet address and a shared signing secret before real-money games can open. Demo games work with both.

This route is the transfer wallet. It moves money between your platform and the player's casino balance at HZURA. On the seamless wallet it answers 409 wallet_mode_mismatch.

operation is exactly BALANCE, DEBIT, CREDIT or ROLLBACK. CREDIT adds money to the player's casino balance. DEBIT takes money out of it, back to you. ROLLBACK undoes one of your own DEBIT or CREDIT requests. BALANCE shows the balance.

While the player plays, bets and wins change the same balance, so it can be different every time you check. Each request either completes fully or is refused. There is never a "pending" result.

A successful answer always has operation, status, currency and balance. balance is a number written as text, without extra zeros: 5.00 is "5" and 12.50 is "12.5". Money requests also return your transaction_id. BALANCE does not.

status is success. If you repeat a request that was later undone, it is rolled_back.

If casino is switched off for your account, CREDIT is refused with casino_access_disabled. BALANCE, DEBIT and ROLLBACK keep working, so players' money can still be taken out.

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

Shows the player's casino balance, after every bet and win so far. A player who has never had money starts at 0.

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"}'

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

Takes amount out of the player's casino balance, back to you. Add it to the player's account on your platform once the answer arrives.

If the balance is too low, you get insufficient_balance and nothing moves. That transaction_id stays refused; to try a smaller amount, use a new transaction_id.

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"}'

If the balance was 12.5, the answer is:

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

Adds amount to the player's casino balance. Take the money from the player's account on your platform first. The player can bet with it as soon as the answer arrives.

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"}'

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

Undoes one of your successful DEBIT or CREDIT requests for the same player. transaction_id is a new id for the undo itself. reference_transaction_id is the request you are undoing. amount and currency must be the same as in that request; a different amount is 400 invalid_wallet.

Undoing a DEBIT puts the money back on the casino balance. Undoing a CREDIT takes it out again. If the player has already spent part of it, you get insufficient_balance.

Each request can be undone once; a second undo is wallet_already_rolled_back. A refused request cannot be undone (wallet_transaction_not_reversible), and an unknown one is wallet_transaction_not_found. You can only undo your own money requests, not bets or wins from games.

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"}'

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

Your transaction_id makes retries safe. If you send the same request again with the same transaction_id, you get the first answer back and money does not move twice. So after a network error or a 503, simply send the same request again.

With the seamless wallet, the player's money stays with you. You give HZURA one HTTPS address. HZURA sends it a JSON POST for every balance check, bet, win and refund in a game. Your answer is passed to the game, so the player always sees your balance.

Games only wait a short time, so your wallet must answer within 3.5 seconds, and accept the connection within 1 second. Redirects are not followed. An answer bigger than 16 KiB counts as no answer.

Every request is signed with a secret that only you and HZURA know. Refuse any request whose signature does not match.

import crypto from "node:crypto";

// rawBody is the exact request body bytes, before JSON parsing.
export function isFromHzura(headers, rawBody, secret) {
  const timestamp = headers["x-hzura-timestamp"];
  const signature = headers["x-hzura-signature"];
  if (!timestamp || !signature) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return (
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  );
}

The fields have the same names as on POST /api/v1/casino/wallet. Fields that do not apply are left out. New optional fields may be added later, so ignore any field you do not know.

{
  "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
}

{
  "operation": "ROLLBACK",
  "player_id": "player-1",
  "currency": "EUR",
  "transaction_id": "7316495900",
  "reference_transaction_id": "7316495845",
  "amount": "10.00",
  "reason": "REFUND",
  "round_id": "1nnrtsy56",
  "game_id": "TK-froggrog",
  "round_completed": true
}

When it worked, answer 200 with the player's balance after this request. balance is text or a number, and never below zero. You can also send your own transaction_id for this movement (1 to 128 letters, digits, -, _, . or :); it is shown to the game as the reference. Leave it out on BALANCE.

{
  "balance": "90.00",
  "transaction_id": "your-txn-1001"
}

To refuse, answer with a 4xx status and one of the error codes below.

{
  "error": "insufficient_balance",
  "message": "Balance is too low"
}

A refused DEBIT stays refused. If the same transaction_id comes again, HZURA gives the same refusal itself and does not call you.

Do not refuse a CREDIT or a ROLLBACK: the win or refund has already happened in the game. A refusal counts as no answer, and the same transaction_id is sent again later.

No answer within 3.5 seconds, a 5xx, a redirect, an unknown error code, or an answer that cannot be read all mean "unknown". Nothing is recorded, and the same transaction_id is sent again, or a ROLLBACK follows for that bet.

• Apply each transaction_id only once. If you already applied it, answer 200 with the balance and the same transaction_id you gave the first time. Do not move money again.
• A ROLLBACK refunds the DEBIT named in reference_transaction_id. If you never applied that debit, or already refunded it, answer 200 with the current balance and move no money.
• A ROLLBACK can arrive before its DEBIT. Remember the refunded id, and if that DEBIT arrives later, refuse it with invalid_request.
• A CREDIT or ROLLBACK can arrive after the game session ended, or after you blocked the player. Apply it anyway.
• BALANCE moves no money. It is sent when a game opens, and whenever the game needs the balance.
• Every attempt is signed again with a new X-Hzura-Timestamp, so a repeated transaction_id comes with a different signature.

• Error codesEvery launch and wallet error, and what to do.
• AuthenticationAPI keys and IP allow-lists.