Balance

Reads the player's balance in the session currency. Never journalled, never retried.

POST/balance

Request

The aggregator sends this request to the client's wallet base URL, signed with the client's credential like a client request, and the client's wallet answers it. The example is signed with the test API key test-key-test-key and the test secret docs-example-signing, at the timestamp 1767225600 with the nonce docs-example-nonce-0001; see Authentication and signing.

Headers

Name
X-Api-Key
Type
string, required
Description
The credential id. Sent together with X-Timestamp, X-Nonce and X-Signature.
Name
X-Signature
Type
string, required
Description
Base64 HMAC-SHA256 of the method, the path with its query, X-Timestamp, X-Nonce and the lowercase hex SHA-256 of the raw body, joined by newlines. Compared in constant time; 30 seconds of tolerance; each nonce is used once.
Name
X-Timestamp
Type
string, required
Description
Unix seconds; within 30 seconds of the receiver's clock. Matches ^[0-9]{1,12}$.
Name
X-Nonce
Type
string, required
Description
Single use per credential, kept until the timestamp plus 30 seconds. At least 16 characters. At most 128 characters.

Body

Name
player_id
Type
string, required
Description
The client's own player id, at most 44 characters so that every provider can carry it namespaced. At least 1 character. At most 44 characters.
Name
session_id
Type
string (uuid), required
Description
A UUID v7.
Name
provider
Type
string, required
Description
One of drakon, cocktail, games360.
Name
game_id
Type
string (uuid), required
Description
A UUID v7.
Name
currency
Type
string, required
Description
One of TRY, EUR, USD, USDT, TON, BTC, AED, AFN, ALL, AMD, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TTD, TWD, TZS, UAH, UGX, USN, UYI, UYU, UYW, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XCG, XOF, XPF, YER, ZAR, ZMW, ZWG.

Request

POST

/balance

curl -X POST "https://wallet.example.com/balance" \
  -H "X-Api-Key: test-key-test-key" \
  -H "X-Timestamp: 1767225600" \
  -H "X-Nonce: docs-example-nonce-0001" \
  -H "X-Signature: pnQhJe4SHKDPBJyQVWV4pSDPEsuO7LPHxeabQsWAPdQ=" \
  -H "Content-Type: application/json" \
  -d '{
  "player_id": "player-1001",
  "session_id": "0199c5a0-0000-7000-8000-000000000001",
  "provider": "drakon",
  "game_id": "0199c5a0-0000-7000-8000-000000000002",
  "currency": "EUR"
}'

200

Response

The answer is 200 with application/json.

Name
balance
Type
integer, required
Description
A player's balance in minor units of the currency. It may be below zero after a rollback of a win, which the client must accept. At least -9007199254740991. At most 9007199254740991.
Name
currency
Type
string, required
Description
One of TRY, EUR, USD, USDT, TON, BTC, AED, AFN, ALL, AMD, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TTD, TWD, TZS, UAH, UGX, USN, UYI, UYU, UYW, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XCG, XOF, XPF, YER, ZAR, ZMW, ZWG.

Errors

Each error carries one of these codes in the error object of Errors.

Name
MALFORMED_REQUEST
Type
400
Description
MALFORMED_REQUEST: the request fails the client's validation. A final refusal.
Name
UNAUTHORIZED
Type
401
Description
UNAUTHORIZED: a missing or wrong key, signature, timestamp or nonce. A final refusal.
Name
PLAYER_NOT_FOUND
Type
404
Description
The player or the transaction does not exist. A final refusal.
Name
TRANSACTION_NOT_FOUND
Type
404
Description
The player or the transaction does not exist. A final refusal.
Name
DUPLICATE_TRANSACTION
Type
409
Description
DUPLICATE_TRANSACTION: the transaction_id was used with a different request. A final refusal.
Name
PLAYER_BLOCKED
Type
422
Description
A business refusal of the player, the funds, a limit or the currency. A final refusal.
Name
INSUFFICIENT_FUNDS
Type
422
Description
A business refusal of the player, the funds, a limit or the currency. A final refusal.
Name
PLAYER_LIMIT_REACHED
Type
422
Description
A business refusal of the player, the funds, a limit or the currency. A final refusal.
Name
CURRENCY_MISMATCH
Type
422
Description
A business refusal of the player, the funds, a limit or the currency. A final refusal.
Name
INTERNAL_ERROR
Type
5XX
Description
A 5xx, a timeout, a network error, or any status or body this document does not list as a refusal (a 4xx whose body carries no canonical code among them) is an unknown outcome. A body, when there is one, has the wallet error shape with INTERNAL_ERROR, the only code the error table gives a 5xx; the aggregator treats any 5xx as an unknown outcome whatever its body.

Response

{
  "balance": 97500,
  "currency": "EUR"
}