Wallet API

How it works

Your wallet API is a small HTTPS service on your side. Our game server calls it for every login and every balance change; you stay the single source of truth for balances.

Base URL and methods

You give us one base URL, e.g. https://wallet.yourcasino.com/vashub-wallet, and we append the method:

Method	Called	Page
`POST /auth`	Checks a launch token and tells the game who the player is and what they can play with.	Authentication
`POST /info`	Returns a player's current balance.	Player info
`POST /withdraw`	Takes money from the player: a bet's stake, or the money a player shares in chat.	Withdraw
`POST /deposit`	Pays money to the player: a win, a rollback, or money received from chat or a free bet.	Deposit

Requests

POST with a JSON body and Content-Type: application/json, over HTTPS.
Three headers on every call: X-Client-ID, X-Client-TS and X-Client-Signature. Check them before anything else: Securing requests.
Parse the body after checking the signature, and ignore fields you don't know: we may add some.

Replies

Reply with JSON: code, message and, when the call succeeded, data. Use the same number for the HTTP status and code.

{
  "code": 200,
  "message": "ok",
  "data": {
    "old_balance": 1500.5,
    "new_balance": 1400.5
  }
}

This is how our game server reads your reply:

Your reply	We treat it as
HTTP 2xx with `code: 200` or `message: "ok"`	Accepted. For money calls: the money moved.
HTTP 4xx with a JSON body	Refused. Nothing moved. Your `message` is shown to the player, so keep it short and friendly.
HTTP 5xx, no reply within 10 seconds, or a body that isn't JSON	Unclear. Money may or may not have moved: see Timeouts and retries.

Amounts

amount and every balance are numbers in the same unit, agreed for your integration:

Unit	Example: KES 10.50	Notes
Currency units (default)	`10.5`	Up to two decimals.
Minor units (×100)	`1050`	Whole numbers: cents.
Thousandths (×1000)	`10500`	Whole numbers, as some providers use.

Return balances in the unit you receive amounts in. Each game server works in one currency.

Transaction IDs and repeats

provider_tx_id is our ID for the bet. A bet's withdraw and its win or rollback deposit carry the same provider_tx_id: tell them apart by the method and action.
Make every money call idempotent by method + `action` + `provider_tx_id` (and the X-Client-ID, if several of our servers call you).
When the same call comes again, don't move money and don't return an error: reply 200 with the first call's data.

Actions

action	Method	Meaning
`bet`	`/withdraw`	A bet's stake.
`rain`	`/withdraw`	Money a player shares in chat: a rain or a tip.
`win`	`/deposit`	A winning bet's full payout (stake × multiplier).
`rollback`	`/deposit`	A stake returned (cancelled bet, missed round).
`claim`	`/deposit`	Rain or a tip received, or a free bet's winnings. No matching withdraw.

Free bets cost the player nothing, so they make no withdraw; a winning free bet's profit arrives as a claim.

Balances must add up

Every successful withdraw and deposit reply needs old_balance and new_balance. We check that they differ by exactly amount: a withdraw that doesn't add up is not accepted and its bet doesn't play.

Timeouts and retries

Call	If the answer is unclear
`/auth`, `/info`	The player sees “Your wallet is not responding” and can try again.
`/withdraw`	The bet doesn't play. It's held for reconciliation by `provider_tx_id`, and the player is asked to contact you if their balance went down. We don't retry withdraws.
`/deposit`	We retry the same call about once a minute (currently up to 6 attempts, within 12 hours of the bet); then it's held for you and us to settle.

We wait up to 10 seconds for a reply and log anything slower than 2 seconds: aim for well under a second.

A round, call by call

A player bets 100 and cashes out at 2.50×:

POST /vashub-wallet/auth      {"user_token":"8f3c…","token":"8f3c…","platform":"mobile","currency":"KES"}
→ 200 {"code":200,"message":"ok","data":{"user_id":"100245","balance":1500.5,…}}

POST /vashub-wallet/withdraw  {…,"amount":100,"action":"bet","provider_tx_id":5823019,…}
→ 200 {"code":200,"message":"ok","data":{"old_balance":1500.5,"new_balance":1400.5,…}}

POST /vashub-wallet/deposit   {…,"amount":250,"action":"win","provider_tx_id":5823019,"withdraw_provider_tx_id":5823019,…}
→ 200 {"code":200,"message":"ok","data":{"old_balance":1400.5,"new_balance":1650.5,…}}

Had the plane flown away first, the bet would have lost and there would be no third call.