Skip to main content

Single Wallet API Introduction

What is Single Wallet Mode?​

Single Wallet mode is a gaming integration solution where member balances are centrally managed by the operator. When placing bets or settling transactions, the gaming platform calls the operator's API in real-time to check balances and process transactions.

Differences with Transfer Wallet​

FeatureSingle WalletTransfer Wallet
Balance ManagementManaged by OperatorManaged by Platform
Betting ProcessReal-time DeductionTransfer then Bet
Implementation RequirementsOperator implements 4 APIsOperator calls Platform APIs
Fund FlowNo Transfer RequiredTransfer In/Out Required
Use CaseOperators with existing wallet systemsNewly established gaming platforms

In Single Wallet mode:

  1. 🎮 Players play games on the gaming platform
  2. 🔐 Gaming platform verifies member identity via operator API
  3. 💰 For each bet, the platform calls operator API for deduction and rewards
  4. 📊 All balances and transaction records are managed by the operator

Documentation Structure​

This documentation is divided into two main sections:

📘 Operator API Implementation (Required)​

The operator must provide the game provider with a callback URL for API calls. The game provider will use the action parameter to distinguish between different operations:

ActionDescriptionDocumentation
balanceQuery member available balance in real-timeView Documentation
betNSettleHandle game betting and settlement (deduction + rewards)View Documentation
rollbackRollback abnormal transactionsView Documentation
retryBetA retry mechanism dedicated to item and operator card retries.View Documentation

Unified Endpoint Example: POST https://operator.example.com/api/wallet

👉 Start Implementation: Operator API Implementation Guide

📗 Platform APIs (Called by Operator)​

Operators can call the following platform APIs for member management and queries:

Version Information​

  • Version: v2.0.0
  • Type: Single Wallet Mode
  • Encryption Method: AES-256-GCM
  • Authentication Method: JWT Token + SHA256 Signature

Decrypted request content typically includes:

  • token: Gaming platform authentication token
  • account: Player Account
  • nonce: Unique transaction identifier (UUID)
  • timestamp: Request timestamp

Common Response Format​

Success Response (With Data)​

All non-operator implemented API responses are in plain JSON format, following this structure:

{
  "code": 0,
  "message": "No error.",
  "data": {
    // API-specific response data
  },
  "logUUID": "042d4437-cbe3-440a-8acf-4baff3722fd6"
}
FieldTypeDescription
codenumberStatus code, 0 indicates success
messagestringStatus message, "No error." on success
dataobjectAPI response data, varies by API
logUUIDstringRequest tracking ID for troubleshooting and log queries

Success Response (No Data)​

For operations that do not require returning data, the response format is as follows:

{
  "code": 0,
  "message": "No error.",
  "logUUID": "042d4437-cbe3-440a-8acf-4baff3722fd6"
}

Error Response​

{
  "code": 7,
  "message": "Internal server error.",
  "logUUID": "6589bf8d-fe74-48bd-841a-71bf8f848f86"
}
FieldTypeDescription
codenumberError code (non-zero), refer to error code table for each API
messagestringError description message
logUUIDstringRequest tracking ID for troubleshooting and log queries

Testing Recommendations​

  • Use stage environment for development testing
  • Ensure all error scenarios are properly handled
  • Verify uniqueness of nonce
  • Test network exceptions and timeout situations