Skip to main content

Operator API Implementation Description

In Single Wallet Mode, the operator is required to implement a unified API for the platform to call, enabling balance queries, bet settlement, and transaction processing.

Architecture Overview​

In Single Wallet Mode, the operator is required to implement a unified API for the platform to call, enabling balance queries, bet settlement, and transaction processing.

API Implementation Description​

The operator must provide a callback URL on its own server. The platform will determine which operation to execute based on the action parameter in the request:

ActionDescriptionPriority
balanceQuery the member’s available balance in real timeRequired
betNSettleHandle game betting and settlementRequired
rollbackRoll back abnormal transactionsRequired
retryBetBet retry mechanismRequired

Unified URL​

The operator only needs to provide a single callback URL, for example:

https://operator.example.com/api/wallet

After decrypting the request parameters, the platform will include the action field to distinguish different operations.

Implementation Requirements​

1. Security Requirements​

  • ✅ Encrypted Transmission: All request payloads are encrypted using AES-256-GCM; responses are returned as plaintext JSON
  • ✅ HTTPS: HTTPS is mandatory in the production environment
Encryption Description

Algorithm: AES-256-GCM

  • Key Length: 256 bits (32 bytes)
  • IV Length: 96 bits (12 bytes)
  • Authentication Tag Length: 128 bits (16 bytes)

cipherText Format:

ivBase64(16 characters) + authTagBase64(24 characters) + encryptedDataBase64

2. 響應格式要求​

2. Response Format Requirements​

Response Format Description

All operator API responses must be returned as plaintext JSON and follow the fixed format below:

{
  status: '0000',
  errText: '',
  balance: 12345.67,
  responseTime: '2024-12-11T01:23:38.271Z'
}
FieldTypeDescription
statusstringStatus code; refer to each API description for details
errTextstringError message; empty string on success
balancenumberMember balance after the operation
responseTimestringResponse time

3. Performance Requirements​

  • ⚡ Response Time: The average response time should be less than 3000 ms(3s); requests exceeding this limit will be considered a timeout

FAQ​

Q1: How are different operations distinguished?​

A: The platform includes an action field (balance, betNSettle, rollback, retryBet) in the decrypted request parameters. The operator should route the request to the corresponding handling logic based on this field.

Q2: How long should the token validity be?​

A: A validity period of 24 hours is recommended. The token should be invalidated when the member closes the game or logs out.

Q3: What decimal precision should be used for balances?​

A: Support up to 4 decimal places (0.0001). At a minimum, support 2 decimal places (0.01).

Q4: How long before a transaction is considered timed out if no response is received?​

A: 3 seconds.

Q5: Which transactions will enter the RetryBet flow?​

A: The transaction of Item and Operator Card, if the response times out or encounters an error will not trigger bet cancellation, retry will be called via the RetryBet API.

Q6: Can the callback URL be adjusted?​

A: Yes. The platform does not enforce a specific format for the callback URL returned in transactions. The exact configuration and validation can be managed via the backend settings.

Technical Support​

If you encounter any issues during implementation, please contact the TG Technical Support team.

Next Steps​