Wallet API Contract

The casino mints a short-lived JWT and redirects the player into the game iframe:

https://rocketrushx.io/embed
  ?operator=acme
  &token=<JWT>
  &currency=USDC
  &lang=en
  &return_url=https://acme.casino/lobby

JWT payload (HS256, signed with operator's shared secret):

{
  "sub": "player_8f3a1c",      // casino's player ID
  "op":  "acme",                // operator slug
  "cur": "USDC",                // ISO/ticker
  "bal": 250.00,                // initial balance hint
  "iat": 1730000000,
  "exp": 1730000600,            // 10 min TTL
  "sid": "session_xyz"          // game session ID
}

POST https://acme.casino/api/rrx/bet
X-RRX-Signature: t=1730000000,v1=<hmac_sha256(secret, t + "." + body)>
X-RRX-Idempotency-Key: bet_round42_player8f3a1c
Content-Type: application/json

{
  "session_id": "session_xyz",
  "player_id":  "player_8f3a1c",
  "round_id":   "round_42",
  "currency":   "USDC",
  "amount":     "5.00",
  "rocket":     "blue_streak",
  "seed_hash":  "a3f9...e21c"   // committed before round
}

200 OK
{ "txn_id": "tx_998", "balance": "245.00" }

402 Payment Required
{ "error": "INSUFFICIENT_FUNDS" }

POST https://acme.casino/api/rrx/win
{
  "session_id": "session_xyz",
  "round_id":   "round_42",
  "bet_txn_id": "tx_998",
  "currency":   "USDC",
  "amount":     "12.50",
  "multiplier": 2.50,
  "crash_at":   3.87,
  "server_seed": "9e4d...",   // revealed post-round
  "client_seed": "user_input"
}

200 OK
{ "txn_id": "tx_999", "balance": "257.50" }

POST https://acme.casino/api/rrx/refund
{
  "session_id": "session_xyz",
  "round_id":   "round_42",
  "bet_txn_id": "tx_998",
  "reason":     "ROUND_VOIDED" | "TIMEOUT" | "OPERATOR_REQUEST"
}

200 OK
{ "txn_id": "tx_1000", "balance": "250.00" }

GET https://acme.casino/api/rrx/balance?player_id=player_8f3a1c&currency=USDC

200 OK
{ "balance": "245.00", "currency": "USDC" }

• HMAC-SHA256 over timestamp + "." + raw_body. Reject if timestamp drift > 60s.
• Idempotency key required on all writes. Replays return the original response.
• TLS 1.2+ on every endpoint. IP-allowlist Rocket Rush X egress IPs (published in operator dashboard).
• Amounts as decimal strings, never floats. Currency code per ISO-4217 or ticker.
• Round IDs are globally unique. bet_txn_id ties win/refund back to the original bet.

INSUFFICIENT_FUNDS      402   Player balance below bet amount
INVALID_SIGNATURE       401   HMAC mismatch / expired timestamp
DUPLICATE_TXN           409   Idempotency key already used (return original)
SESSION_EXPIRED         401   JWT exp passed; player must relaunch
PLAYER_LOCKED           403   Operator-side self-exclusion / KYC freeze
CURRENCY_NOT_SUPPORTED  400   Player wallet does not support requested currency
INTERNAL                500   Retry with backoff (max 3, exponential)