Wallet

Debit (place bet)

Subtracts the stake from the player’s wallet when a bet is placed.

Every debit is eventually settled by exactly one Credit or one Rollback carrying the same gameRoundId — never both.

Free rounds: when reason is freeround the stake is 0. Deduct nothing, but still create the transaction and return a valid response.

The status code you choose here is a contract, not a formality — see the response list below. 422 tells Zero-Dash the transaction definitively does not exist on your side; 500 tells us it might, and we will send a rollback.

POST

debit

curl --request POST \
  --url https://{host}/debit \
  --header 'Content-Type: application/json' \
  --header 'X-Zd-Signature: <api-key>' \
  --header 'X-Zd-Timestamp: <api-key>' \
  --data '
{
  "playerId": "acct_8f2c19",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "transactionId": "test-transaction-1112",
  "gameId": "lucky-duck",
  "gameRoundId": "round-1234",
  "stake": {
    "amount": 1,
    "currency": "USD"
  },
  "reason": "paid"
}
'

{
  "operatorTransactionId": "op-tx-55901",
  "balance": {
    "amount": 95,
    "currency": "USD",
    "updatedAt": "2026-01-29T14:05:29.678Z"
  },
  "createdAt": "2026-01-29T14:05:29.678Z"
}

{
  "message": "missing field gameRoundId"
}

{
  "message": "invalid signature"
}

{
  "message": "insufficient balance"
}

{
  "message": "wallet unavailable, transaction not created"
}

{
  "message": "internal error"
}

Authorizations

X-Zd-Signature

string

header

required

Hex-encoded HMAC-SHA512(apiPath|timestamp|data, secretKey) computed by Zero-Dash. Recompute it and compare before doing anything else. See Request signature.

X-Zd-Timestamp

string

header

required

Unix time in milliseconds, and the exact value that was signed. Reject requests older than 5 minutes.

Body

application/json

playerId

string

required

Player account ID.

transactionId

string

required

Zero-Dash ID of this bet transaction. Use it as your idempotency key.

gameId

string

required

Slug of the game the round belongs to.

Example:

"lucky-duck"

gameRoundId

string

required

Groups the bet with its settlement. The credit or rollback that settles this bet carries the same value.

Example:

"round-1234"

stake

object

required

Decimal amount to subtract from the balance. 0 for free rounds.

Show child attributes

token

string

The session token from game launch.

reason

enum<string>

Type of the bet. paid is real money; freeround is a free round — each free spin is a separate bet with its own debit call.

Available options:

paid,

freeround

freeRoundData

object

Present only when reason is freeround.

Show child attributes

Response

Bet accepted and the stake was subtracted.

operatorTransactionId

string

required

Your internal transaction ID. Stored by Zero-Dash for troubleshooting only.

balance

object

required

The player's balance after the operation was applied.

Show child attributes

createdAt

string<date-time>

Transaction creation date (ISO-8601 UTC). Defaults to the time of processing when omitted.

curl --request POST \
  --url https://{host}/debit \
  --header 'Content-Type: application/json' \
  --header 'X-Zd-Signature: <api-key>' \
  --header 'X-Zd-Timestamp: <api-key>' \
  --data '
{
  "playerId": "acct_8f2c19",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "transactionId": "test-transaction-1112",
  "gameId": "lucky-duck",
  "gameRoundId": "round-1234",
  "stake": {
    "amount": 1,
    "currency": "USD"
  },
  "reason": "paid"
}
'

{
  "operatorTransactionId": "op-tx-55901",
  "balance": {
    "amount": 95,
    "currency": "USD",
    "updatedAt": "2026-01-29T14:05:29.678Z"
  },
  "createdAt": "2026-01-29T14:05:29.678Z"
}

{
  "message": "missing field gameRoundId"
}

{
  "message": "invalid signature"
}

{
  "message": "insufficient balance"
}

{
  "message": "wallet unavailable, transaction not created"
}

{
  "message": "internal error"
}

Overview

Wallet

Troubleshooting

Debit (place bet)

Authorizations

Body

Response