Seamless Wallet API Introduction

What is Seamless Wallet Mode?

Seamless Wallet Mode is a Games integration solution, where Player's Balance is uniformly managed by the Operator. When the VP performs operations such as Bet and Settlement, it will immediately call the API provided by the Operator to Query Balance and process transactions.

Differences with Transfer Wallet

Feature	Seamless Wallet	Transfer Wallet
Balance Management	Managed by Operator	Managed by VP
Betting Process	Real-time Deduction	Transfer then Bet
Implementation Requirements	Operator implements 4 APIs	Operator calls VP APIs
Fund Flow	No Transfer Required	Transfer In/Out Required

In Seamless Wallet mode:

1. 🎮 Players play games on VP
2. 🔐 VP verifies player identity via operator API
3. 💰 For each bet, VP 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 needs to provide the VP with a set of callback URLs for the VP to call and use. The VP will distinguish different operations via the action parameter:

Action	Description	Documentation
balance	Query player available balance in real-time	View Documentation
betNSettle	Handle game betting and settlement (deduction + rewards)	View Documentation
rollback	Rollback abnormal transactions	View Documentation
retryBet	Retry mechanism specifically for retrying Items and Operator Cards	View Documentation

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

👉 Start Implementation: Operator API Implementation Guide

📗 VP APIs (Called by Operator)

Operators can call the following VP APIs for player management and queries:

• Player Management

  • Create Player - Register new players on VP
  • Query Online Players - View currently online players
  • Kick Player - Force Kick Player

• Game Management

  • Query Game List - Query available games
  • Query popular games - Query popular games
  • Open Game - Generate game launch URL

• Operator Card Management

  • Operator CardDescription - Operator Card Features
  • Get Operator Card Information - Get Operator Card Information
  • Send Operator Card - Send Operator Card
  • Send Simple FreeSpin Operator Card - Send simplified FreeSpin Operator Card
  • Send Simple FeatureGame Operator Card - Send simplified FeatureGame Operator Card
  • Cancel Operator Card - Cancel Used Operator Card
  • Query Operator Card Status - Query Operator Card Usage Status

• Bet Logs & Reports

  • Query Bet Logs - Query player bet records
  • Query Bet Detail - Query single bet details
  • Query Bet Replay - Generate bet replay URL
  • Query Daily Report - Query daily operation report
  • Query Player Report - Query player report

Version Information

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

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"
}

Field	Type	Description
code	number	Status code, 0 indicates success
message	string	Status message, "No error." on success
data	object	API response data, varies by API
logUUID	string	Request 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"
}

Field	Type	Description
code	number	Error code (non-zero), refer to error code table for each API
message	string	Error description message
logUUID	string	Request tracking ID for troubleshooting and log queries

Testing Recommendations

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