Connect your game
Use your game server to connect players, manage TsuCoin bets and distribute winnings.
1. Activate your game
Create a game in the merchant portal. The platform must activate it before credentials can be issued. Production and Sandbox balances are separate.
2. Issue credentials
Choose your active game and select Issue API credentials. Choose Game and exchange, Game only, Exchange only or Read only. Store the returned client ID and secret in your server's secret storage. The secret is displayed once. Rotate or revoke credentials from the game's API credentials page.
3. Request an access token
Send a JSON POST to /api/v1/auth/token on this host. Supply client_id, client_secret and a scopes array containing only the permissions your operation needs. Read data.access_token and data.expires_in from the response. Cache the token on your server until shortly before expiry.
Send Authorization: Bearer followed by the access token on subsequent API requests. Keep credentials and tokens out of player browsers. Use HTTPS, Content-Type: application/json and a unique Idempotency-Key for each financial operation. Reuse the same key and exact request body after an uncertain response.
Game operations
| Request | Purpose | Permission |
|---|---|---|
| GET /api/v1/auth/context | Verify the authenticated game and permissions | Valid token |
| POST /api/v1/users | Create a player and zero-balance wallet using a unique external_user_reference | user.create |
| GET /api/v1/users | Look up an existing game-linked player | user.read |
| GET /api/v1/wallet/balance | Read balances using platform_user_id | wallet.read |
| POST /api/v1/authorizations | Record verified player consent and limits | authorization.manage |
| POST /api/v1/pools | Withhold participant bets atomically | wallet.hold |
| POST /api/v1/pools/{id}/settle | Credit the recipient wallets and exact amounts supplied by your game server | wallet.hold |
| POST /api/v1/pools/{id}/release | Refund a cancelled game | wallet.hold |
Send whole-number TsuCoin amounts as strings. Settlement payouts must equal the full pool. For a 2,500 TsuCoin pool, your game may allocate 1,000 to the winner and 1,500 to its selected receiving wallet. Omit zero-value allocations. Every recipient must be eligible and authorized.
Player consent is required separately from API access. Configure the game's signing secret under API configuration for the signed consent protocol. Credentials do not authorize spending a player's wallet or creating a funded balance.
Responses and recovery
Successful responses contain success: true, data and request_id. Errors contain success: false, an error code and message, and a request reference. On a timeout, query the operation's current state or retry with its original idempotency key. A settled pool cannot pay twice.
Suspension blocks portal and API access. Credential rotation invalidates tokens issued with the old credential. Review API logs, authorization records and pool payout reports from the portal.