API Documentation

Seamless Wallet integration — v1

1. Authentication

Every request from an Agent must include a signed HMAC header.

Headers:
  Authorization: Bearer <API_KEY>
  X-Signature: hex(HMAC-SHA256(API_SECRET, raw_body))
  Content-Type: application/json

API Key and Secret are generated in your Agent dashboard. The Secret is shown only once.

2. Launch a game session

POST /api/v1/game/launch

{
  "player_id": "user-1234",
  "username": "alice",
  "box_slug": "neon-vault",
  "currency": "USD",
  "return_url": "https://your-site.com/lobby"
}

Response:

{
  "launch_url": "https://lootforge.app/play/...token...",
  "session_token": "...",
  "expires_at": "2026-05-31T18:00:00Z"
}

3. Seamless Wallet callbacks (we → you)

You implement these endpoints on your wallet. We POST when a player bets/wins.

POST {callback_url}/balance

{ "player_id": "user-1234", "currency": "USD" }
→ { "balance": 5000.00 }

POST {callback_url}/bet

{
  "player_id": "user-1234",
  "round_id": "r_abc",
  "amount": 25.00,
  "currency": "USD",
  "idempotency_key": "ik_xyz"
}
→ { "balance": 4975.00, "tx_id": "..." }

POST {callback_url}/win

{
  "player_id": "user-1234",
  "round_id": "r_abc",
  "amount": 120.00,
  "currency": "USD",
  "idempotency_key": "ik_xyz_win"
}
→ { "balance": 5095.00 }

POST {callback_url}/rollback — sent when a bet must be reversed.

4. Provably Fair

Every box opening returns a fairness object:

{
  "server_seed_hash": "...",
  "client_seed": "...",
  "nonce": 1717160000
}

The full server_seed is revealed after the round so players can verify the outcome.

5. Errors

401 invalid_signature
403 ip_not_whitelisted
404 box_not_found
409 idempotency_conflict
422 validation_error            // includes currency_mismatch
422 box_not_priced_in_currency  // box has no price for agent currency
503 wallet_callback_failed

6. Supported currencies

Each Agent is configured with a single base currency: USD or THB. The currency field on every request must match the Agent's configured currency, otherwise we return 422 currency_mismatch. Boxes must have a price defined for the Agent's currency (price_usd or price_thb) — otherwise 422 box_not_priced_in_currency.

Example (THB Agent):

{
  "player_id": "user-1234",
  "username": "alice",
  "box_slug": "neon-vault",
  "currency": "THB"
}

7. Sandbox

After signup, your Agent account starts in sandbox mode with simulated balances. Use the integration tester in your dashboard to fire test launches without touching production.