API reference

Base URL https://api-wallet.iamgame.com/v1. Every path below is relative to it. All request and response bodies are JSON; every amount is an integer base-unit string (see Amounts are integers).

Authentication

Auth is a bearer token in the Authorization header. Which token depends on where the call runs — the three kinds map cleanly onto the endpoint groups below:

Error envelope

Any non-2xx response is a JSON envelope with a stable code. Branch on the code, not the message. Full catalog on the Errors page.

{
  "code": "ledger/insufficient_balance",
  "message": "insufficient session balance for bet",
  "details": { "balance": "100", "amount": "150" }
}

Auth

Player login. The /verify endpoints both create-or-fetch the user, provision a wallet on first sign-in, and return a session. See Authentication.

All three verify endpoints accept an optional referralCode and gameKey for first-touch referral attribution.

Sessions

The relying-party handshake: your game backend verifies a player’s wallet session and gets back a canonical identity, scoped to your app + environment. Mint your own app JWT off the result.

Wallets

The signed-in player’s own wallet. Every route is session-authed and acts only on the caller’s wallet. See Withdraw & export.

Ledger

High-frequency off-chain play. All routes are sk-only; the browser must never reach win/settle. Amounts are integer base-unit strings; writes are idempotent on transactionUuid. See Ledger.

Treasury

Custodial treasury — the real-money cash boundary. sk-only. On-chain movement happens only here; per-minute play stays off-chain in the ledger. currency is the app’s numeric currency id; every move carries a caller-supplied ref. See Treasury.

Custody

Real-money pool escrow (pari-mutuel). sk-only. Lock each stake into a pool, then settle or refund the whole pool atomically under a conservation guard. This is the wallet side of the game’s IWalletCustody seam. See Custody.

Custody routes are only mounted when the app’s pool-escrow model is enabled; a disabled app gets 404 for the whole group.

Referrals

Multi-level referrals across two access tiers. The player-facing routes are session-authed (build “invite friends” UI natively); the payout/chain routes are sk-authed. Payout writes are idempotent on idemKey. See Referrals.

Export

Self-custody export lives under the wallet path. session-authed; needs an idempotencyKey. Preflight first with /wallets/:walletId/export/preflight to check the balance floor.

Examples

Verify a session (server-to-server)

curl -X POST https://api-wallet.iamgame.com/v1/sessions/verify \
  -H "authorization: Bearer $SK" \
  -H "content-type: application/json" \
  -d '{ "sessionToken": "…" }'

Open a ledger session

curl -X POST https://api-wallet.iamgame.com/v1/ledger/sessions \
  -H "authorization: Bearer $SK" \
  -H "content-type: application/json" \
  -d '{
    "userId": "usr_…",
    "gameCode": "crash",
    "currency": "USDC",
    "lockAmount": "1000000"
  }'

Settle a pari-mutuel pool

curl -X POST https://api-wallet.iamgame.com/v1/custody/settle \
  -H "authorization: Bearer $SK" \
  -H "content-type: application/json" \
  -d '{
    "poolId": "pool_42",
    "currency": 3,
    "rake": "50000",
    "payouts": [
      { "betId": "bet_a", "userId": "usr_1", "payout": "1900000" }
    ]
  }'

Where to go next

• Errors — the full code catalog and which are retryable.
• Webhooks — get pushed events instead of polling.
• Choose a money model — ledger vs treasury vs custody.