Skip to main content
Read a balance
Answer the current balance and revision with status: "applied". See Balance reads.

Headers

​
Idempotency-Key
string
required

Equals the body's id.

Example:

"batch_3a787ce18225e69054f0bfbe34e909d7"

​
X-Kinematic-Timestamp
string
required

When the game server signed this attempt, in Unix milliseconds. Refuse a call whose timestamp is more than 60 seconds from your clock. A retry carries a fresh timestamp.

Pattern: ^[0-9]{13}$
Example:

"1793629805120"

​
X-Kinematic-Signature
string
required

Lowercase hex HMAC-SHA256, keyed with your WALLET_SECRET, over the exact UTF-8 bytes of timestamp + "." + body. Compare it in constant time before you parse the body, and refuse the call with a status other than 200 when it does not match.

Pattern: ^[0-9a-f]{64}$
Example:

"0315897c76ddcf819b7603a809501ff9ef1dd518187448e6d41597b6d4b7a021"

Body

application/json
​
id
string
required
Pattern: ^balance_[0-9a-f]{32}$
​
player
string
required

Your stable player ID, the sub of the session token.

Pattern: ^[A-Za-z0-9_-]{1,128}$
Example:

"player_48213"

​
currency
string
required

The currency code. Each currency is a separate account of the player.

Pattern: ^[A-Z0-9]{2,12}$
Example:

"USD"

​
kind
string
required
Allowed value: "balance"
​
amount
string
required
Allowed value: "0"
​
rounds
string[]
required

A bet ID, chosen by the player's browser. The element uses 32 lowercase hex characters.

Pattern: ^[A-Za-z0-9_-]{16,80}$

Response

The current balance.

​
id
string
required

The request's id.

​
status
enum<string>
required

declined only for a debit the player cannot cover. Credits and balance reads are always applied.

Available options:
applied,
declined
​
balance
string
required

The player's balance after this operation, in minor units.

Pattern: ^(0|[1-9][0-9]{0,18})$
Example:

"9900"

​
revision
string
required

Your wallet-wide revision after this operation. It increases with every change to the account, including changes outside kinematic. Two different balances never share a revision.

Pattern: ^(0|[1-9][0-9]{0,18})$
Example:

"9900"

​
currency
string
required

The request's currency.

Pattern: ^[A-Z0-9]{2,12}$
Example:

"USD"