Seamless Wallet API Introduction

What is Seamless Wallet Mode?

Seamless Wallet Mode is a game integration solution where the Player's Balance is uniformly managed by the Operator. When 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
Use Case	Operators with existing wallet systems	Newly established Operators

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 VP with a callback URL for VP to use. VP will differentiate between 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 Items and Operator Cards retries	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

• Game Management

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

• Operator Card Management

  • Get Operator Card Information - Get Operator Card Information
  • Send Operator Card - Send Operator Card
  • Cancel Operator Card - Cancel used Operator Card
  • Get Operator Card Status - Query Operator Card Usage Status

• Bet Logs

  • Query Bet Logs & Reports - Query player bet records
  • Query Bet Details - 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 data to be returned, 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