Skip to content
Wallet integration / Wallet test suite
Wallet integration
On this page

Wallet test suite

Run the whole wallet contract against your wallet in the sandbox, and read what each case sent, expected and got.

Give the suite a test player of yours with at least 10.00 and its currency. It calls your wallet_url exactly as the aggregator will, signed with your key, with ids that start with cg-test- and amounts written in the currency's precision. Its session_id is a fresh UUID that no POST /v1/sessions returned, and its game_id is conformance-test. If your wallet looks sessions up, a session it does not know must not refuse the call: the signature already proves the call is ours. Money cases read the balance back with getbalance rather than trusting the answer; a bet your wallet should have refused but took is rolled back. A full run leaves the player 2.00 up.

POST

/v1/test/wallet-validation

Start a run (sandbox only)

SignedSandbox
Request
{ "player_id": "qa-player-1", "currency": "EUR" }
GET

/v1/test/wallet-validation/{id}

The run and every case so far

SignedSandbox

Poll until status is passed, failed or error. Every case carries outcome (pass, warn, fail, skipped), expected, actual, the request sent, response_status, response_body and docs_path, the page of this guide the rule is on. A run passes with warnings: a warning is a refusal under another code, or a 95th-percentile answer time between one and three seconds; three seconds or more fails. One run at a time, 10 an hour. The same suite runs from the Operator Portal under Validation.

The cases

CaseWhat it checks
signature_refusedA request with a wrong signature is refused with 401
getbalancegetbalance answers the balance as a string
betA bet takes the amount
bet_repeatedThe same bet again moves nothing and gets the first answer
winA win credits the amount
win_repeatedThe same win again moves nothing
win_zeroA win of 0.00 is accepted
rollbackA rollback returns the bet
rollback_repeatedThe same rollback again moves nothing
rollback_unknownA rollback of a bet never seen answers the balance and moves nothing
bet_after_rollbackA bet that arrives after its rollback is refused
rollback_winOur rollback of a win you credited takes the win back
insufficient_fundsA bet over the balance is refused with INSUFFICIENT_FUNDS
currency_mismatchA bet in another currency takes nothing from this currency's balance: refused (CURRENCY_MISMATCH preferred), or taken from a balance in that currency. We never send one; the case guards against a wallet that ignores currency
unknown_playerAn unknown player is refused with PLAYER_NOT_FOUND
win_without_betA win for a round without a bet is credited
free_spins_betA bet with free_spins_id takes nothing
malformedA body without player_id is refused with a 4xx, not a 5xx
response_time95% of answers come back in under a second; 1 to 3 s warns, 3 s or more fails
bonus_amountbonus_amount, where reported, is an amount: a decimal string or a number
The wallet URL must be reachable from the internet: the suite refuses addresses inside a private network, since the report shows what they answer.

In your CI

agg-wallet-suite.mjs starts a run, waits for it, prints every case and writes a JUnit XML report your CI reads. It is a client of the two calls above: the cases run on our side, the same ones as in the Operator Portal. Node 18 or later, no dependencies. It runs against the wallet_url registered for the key, so deploy the wallet under test there first.

bash
export AGG_API_URL=<sandbox base URL from the Operator Portal>
export AGG_KEY_ID=ak_5f2c9e01a34b7d8e2f0c1b6a
export AGG_SECRET=<sandbox secret>
node agg-wallet-suite.mjs --player qa-player-1 --currency EUR --junit wallet-suite.xml

# the same without Node on the machine
docker run --rm -e AGG_API_URL -e AGG_KEY_ID -e AGG_SECRET -v "$PWD:/w" -w /w node:22-alpine   node agg-wallet-suite.mjs --player qa-player-1 --currency EUR
Exit codeMeaning
0Every case passed; warnings do not fail the build
1A case failed: the report names it, what was expected and the page of this guide
2No verdict: the run was refused (one at a time, 10 an hour), the options are incomplete, or it did not finish within --timeout (300 s)

Reference wallet

reference-wallet.mjs is a wallet written to this contract in one file: signature check with both secrets during a rotation, idempotency by transaction_id, rollback of a bet or a win and before either arrives, money as strings in the currency's precision. It passes every case. When a case fails for you, compare your answer with its answer to the same request.

bash
AGG_SECRET=<sandbox secret> PLAYER_ID=qa-player-1 CURRENCY=EUR DECIMALS=2 BALANCE=1000.00 PORT=8080 node reference-wallet.mjs
# wallet_url: https://<your host>/wallet
Balances live in memory and reset on restart. It is an example to read, not a wallet to hold money.