Documentation contents

Developer / Public API Reference

AG Game Open Platform API

V5.0.0

Integrate gaming-platform capabilities into an existing system through the game catalog, game sessions, single-wallet callbacks or transfer-wallet endpoints. All platform endpoints use JSON request bodies; the common request headers and signing rules apply to every request.

Base URLhttps://{base-url}

Request methodPOST

Content-Typeapplication/json

Wallet modelsSingle wallet / transfer wallet

Public reference, not a complete production contract

This page publishes the endpoint catalog, signing method, representative fields and redacted examples for technical evaluation. The real base URL, credentials, complete field constraints, final callback list and production configuration must be confirmed through the controlled integration process. The examples contain no usable credentials; do not send real player or transaction data through public contact channels.

Keep keys only in a controlled server environment

Separate test and production configuration. Never place a signing key in browser code, client packages, logs, tickets or chat. Public placeholder values are not production configuration.

Minimal request example

The following example creates a game session. Before sending it, calculate the signature from the final JSON string.

curl --request POST 'https://{base-url}/game/v5/game/url' \
  --header 'Content-Type: application/json' \
  --header 'X-MERCHANT-CODE: {merchant-code}' \
  --header 'X-TIMESTAMP: {timestamp}' \
  --header 'X-NONCE: {nonce}' \
  --header 'X-SIGN: {hmac-sha256-signature}' \
  --header 'X-CONTENT-PROCESSING-TYPE: {processing-type}' \
  --data-raw '{
    "reqTraceId": "trace-demo-001",
    "gameCode": "{game-code}",
    "playerId": "player-demo-001",
    "currencyCode": "{currency-code}",
    "language": "en",
    "terminalType": "PC",
    "returnUrl": "https://{merchant-host}/lobby",
    "ipAddress": "192.0.2.10"
  }'

Authentication and signing

The signing type is fixed as HmacSHA256, and common headers must be sent with every request.

Common request headers

Header	Type	Required	Description
`X-MERCHANT-CODE`	string	Required	Merchant code assigned to the platform
`X-TIMESTAMP`	string	Required	Timestamp at the time of the request
`X-NONCE`	string	Required	Random string used for each request
`X-SIGN`	string	Required	Request signature generated with HmacSHA256
`X-CONTENT-PROCESSING-TYPE`	string	Required	Content-processing type supplied according to the integration configuration

Signing string

1
Serialize the request body as the final JSON string body.
2
Concatenate the fields in the following exact order without separators.
3
Use the signing key to perform HMAC-SHA256 and place the result in X-SIGN.

merchantCode + timestamp + nonce + signType + body

The request body must be byte-for-byte identical

The body used for signing must exactly match the request body actually sent. Reformatting JSON, changing field order or changing whitespace before sending can produce C10004.

import { createHmac } from "node:crypto";

const signType = "HmacSHA256";
const body = JSON.stringify(requestBody);
const signingText = merchantCode + timestamp + nonce + signType + body;

const signature = createHmac("sha256", secretKey)
  .update(signingText, "utf8")
  .digest("hex");

Common response

Business results are returned through code in the response body; do not rely on HTTP status alone to determine a transaction result.

Field	Type	Description
`code`	string	Business result code
`msg`	string	Result message
`success`	boolean	Success flag in the response example
`data`	object	Endpoint response data

{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {}
}

Catalog and representative endpoints

Select the endpoint group that corresponds to the merchant wallet architecture. All platform endpoints use POST.

/

Game catalog and sessions

POST/game/v5/providers

List game providers

POST/game/v5/categories

List game categories

POST/game/v5/games

List games with pagination

POST/game/v5/game/url

Create a player game session and obtain a launch URL

POST/game/v5/player/force/logout

Force the end of a player game session

Single-wallet callbacks

POST{MERCHANT-URL}/wallet/balance

Query a player wallet balance

POST{MERCHANT-URL}/player/info

Query player information

POST{MERCHANT-URL}/wallet/bet

Receive a bet notification

POST{MERCHANT-URL}/wallet/win

Receive a settlement or bet-settlement notification

POST{MERCHANT-URL}/wallet/cancel

Receive an order-cancellation notification

Transfer wallet

POST/game/v5/cash/deposit

Transfer funds into a player game wallet

POST/game/v5/cash/withdraw

Transfer funds out of a player game wallet

POST/game/v5/cash/balance

Query a player game-wallet balance

POST/game/v5/cash/transaction

List wallet transaction records with pagination

POST/game/v5/cash/force/withdraw/all

Force the withdrawal of all funds from a player game wallet

Records and merchant

POST/game/v5/game/record

List game records with pagination

POST/game/v5/merchant/info

Query the current merchant configuration and wallet information

Single-wallet callback scope

Whether /wallet/bet and /wallet/cancel must be implemented by the merchant depends on the actual integration configuration and final technical agreement. Confirm the callback list before integration testing.

POST`/game/v5/game/url`Create game session

Creates a game session for a specified player and returns a URL that can launch the game.

Authentication: common request headersContent-Type: application/json

Request fields

Field	Type	Required	Description
`reqTraceId`	string	Required	Unique request identifier; must not be reused
`gameCode`	string	Required	Game code
`playerId`	string	Required	Unique player identifier on the merchant side
`currencyCode`	string	Required	Wallet currency code
`language`	string	Required	Game-interface language
`terminalType`	string	Optional	Terminal type: PHONE or PC; PHONE by default
`returnUrl`	string	Optional	Return URL after the player leaves the game
`ipAddress`	string	Required	Player IPv4 or IPv6 address
`subMerchantCode`	string	Optional	Sub-merchant code; cannot contain an underscore
`nickName`	string	Optional	Player nickname
`avatarUrl`	string	Optional	Player avatar URL

                          {
  "reqTraceId": "trace-demo-001",
  "gameCode": "{game-code}",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "language": "en",
  "terminalType": "PC",
  "returnUrl": "https://{merchant-host}/lobby",
  "ipAddress": "192.0.2.10"
}

                          {
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "gameCode": "{game-code}",
    "playerId": "player-demo-001",
    "gameUrl": "https://{game-launch-host}/session/{token}",
    "expireTime": "2026-08-08T10:30:00Z"
  }
}

Response data

Field	Type	Returned	Description
`data.gameCode`	string	Required	Game code
`data.playerId`	string	Required	Player identifier
`data.gameUrl`	string	Required	Game launch URL
`data.expireTime`	string	Optional	Session expiry time

POST`{MERCHANT-URL}/wallet/win`Wallet settlement callback

In single-wallet mode, the platform sends a payout or bet-settlement notification to the merchant wallet. The merchant should process the transaction idempotently and return the resulting balance in the response.

Direction: platform → merchantType: win / bet_win

Request fields

Field	Type	Required	Description
`reqTraceId`	string	Required	Unique request identifier
`playerId`	string	Required	Unique player identifier on the merchant side
`currencyCode`	string	Required	Wallet currency code
`gameCode`	string	Required	Game code
`transactionId`	string	Required	Unique platform transaction identifier
`roundId`	string	Required	Unique game-round identifier
`betId`	string	Required	Related bet identifier
`betAmount`	string	Required	Bet amount for this transaction
`winAmount`	string	Required	Payout amount for this transaction
`isFree`	boolean	Required	Whether the record was generated by a free game
`isEnd`	boolean	Required	Whether the current game round has ended
`betTime`	string	Required	Bet time
`settledTime`	string	Required	Settlement time
`type`	string	Required	Notification type: win or bet_win

                          {
  "reqTraceId": "trace-demo-002",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "gameCode": "{game-code}",
  "transactionId": "txn-demo-002",
  "roundId": "round-demo-001",
  "betId": "bet-demo-001",
  "betAmount": "10.00",
  "winAmount": "18.50",
  "isFree": false,
  "isEnd": true,
  "betTime": "2026-08-08T10:00:00Z",
  "settledTime": "2026-08-08T10:00:08Z",
  "type": "bet_win"
}

                          {
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "merchantBetId": "merchant-bet-demo-001",
    "balance": "108.50"
  }
}

POST`/game/v5/cash/deposit`Transfer funds into game wallet

In transfer-wallet mode, transfers the specified amount from the merchant side into a player game wallet.

Wallet model: transfer walletTransaction key: merchantTransactionId

Request fields

Field	Type	Required	Description
`reqTraceId`	string	Required	Unique request identifier used for request tracing
`playerId`	string	Required	Unique player identifier on the merchant side
`currencyCode`	string	Required	Wallet currency code
`amount`	string	Required	Transfer amount
`merchantTransactionId`	string	Required	Unique merchant transaction identifier used for transaction reconciliation

                          {
  "reqTraceId": "trace-demo-003",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "amount": "100.00",
  "merchantTransactionId": "merchant-txn-demo-001"
}

                          {
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "balance": "100.00"
  }
}

Transaction reconciliation

Generate a unique merchantTransactionId for every transfer and retain the request and business result so that the final status can be reconciled through the transaction-query endpoint.

POST`/game/v5/game/record`Query game records

Queries a player's bet and payout records by time range with pagination.

Request fields

Field	Type	Required	Description
`reqTraceId`	string	Required	Unique request identifier
`pageNum`	integer	Required	Page number
`pageSize`	integer	Required	Records per page
`reqData.startTime`	string	Required	Query start time
`reqData.endTime`	string	Required	Query end time
`sort`	string	Optional	Sort order

                          {
  "reqTraceId": "trace-demo-004",
  "pageNum": 1,
  "pageSize": 50,
  "reqData": {
    "startTime": "2026-08-08T00:00:00Z",
    "endTime": "2026-08-08T23:59:59Z"
  },
  "sort": "DESC"
}

                          {
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "gameRecordList": [{
      "orderNo": "order-demo-001",
      "playerId": "player-demo-001",
      "betAmount": "10.00",
      "winAmount": "18.50",
      "betTime": "2026-08-08T10:00:00Z",
      "winTime": "2026-08-08T10:00:08Z",
      "gameCode": "{game-code}",
      "currencyCode": "{currency-code}",
      "roundId": "round-demo-001"
    }]
  }
}

Technical FAQ

Common integration-testing questions about signing, wallets, idempotency, timeouts and session queries.

How does AG API generate a request signature?

Serialize the final request body as body, then concatenate merchantCode + timestamp + nonce + signType + body in that order without separators. signType is fixed as HmacSHA256. Compute HMAC-SHA256 with the signing key and place the result in X-SIGN. The body used for signing must be exactly the same as the body sent.

View the authentication and signing example

Why is C10004 returned?

C10004 indicates signature verification failure. First check the merchant code, timestamp, nonce, signing key and fixed HmacSHA256 type. Then confirm that middleware has not reserialized the signed JSON string, changed field order or changed whitespace. Keep reqTraceId and the request time for diagnosis, but never record the signing key.

View the full error-code list

What is the difference between single wallet and transfer wallet?

In single-wallet mode, the merchant maintains the player balance and the platform collaborates with the merchant wallet through balance, bet and settlement callbacks. In transfer-wallet mode, the merchant calls endpoints such as /game/v5/cash/deposit and /game/v5/cash/withdraw to transfer funds between the merchant system and the player game wallet. The model used depends on the merchant integration configuration and should not be mixed within the same transaction flow.

View the wallet endpoint catalog

How should repeated wallet callbacks be handled?

The merchant should use transactionId as the idempotency basis for callback transactions. When the same transaction arrives again, return the previously confirmed processing result and balance; do not debit or credit it again. Retain the request, business result and final balance for reconciliation. Whether /wallet/bet and /wallet/cancel are required remains subject to the merchant's final callback list.

View the wallet settlement callback

Can a transfer request be retried directly after a timeout?

Do not create a new transaction and repeat the transfer while the result is unknown. First use the original merchantTransactionId to call /game/v5/cash/transaction and query the result, then decide whether to resend according to the final technical agreement. This avoids duplicate accounting when the first request succeeded but its response was lost on the network.

View the game-wallet transfer example

What are reqTraceId and merchantTransactionId used for?

reqTraceId is the unique tracking identifier for each request. It is used to associate call logs and diagnose one request; it should be generated and recorded per request even when retrying. merchantTransactionId is the merchant-side unique transaction identifier, used for transfer reconciliation, result queries and preventing the same business transaction from being processed repeatedly. They have different purposes and cannot replace one another.

How is a player game session created?

Obtain an available gameCode from the game catalog, prepare the player identifier, currency, language and IP address, then call /game/v5/game/url with the common request headers. A successful response returns gameUrl and may return expireTime; the client should open the URL while the session is valid.

View create game session

How are player game records queried?

Call /game/v5/game/record with pageNum, pageSize, and the reqData.startTime and reqData.endTime range; sort can be supplied when needed. Read order, player, bet amount, payout, game code and round records from gameRecordList in the response, and continue querying by page.

View the game-record endpoint

Error codes

Record reqTraceId, the business error code and request time to help diagnose issues quickly.

Code	Message	Recommended action
`C10000`	Request succeeded	Request succeeded
`C10001`	Base service exception	Base service exception
`C10002`	Request parameter error	Check request fields and data types
`C10003`	Invalid request header	Check the five common request headers
`C10004`	Signature error	Check signing order, key and original request body
`C20001`	Merchant code absent	Check the merchant code
`G10001`	Game service exception	Game service exception
`G20001`	Player ID empty	Provide playerId
`G20002`	Game ID absent	Check the game code
`G20003`	Game offline	The game is offline or unavailable
`G30001`	Game user session expired	Create a new game session
`G30002`	Merchant balance insufficient	Merchant balance is insufficient
`G30003`	Player balance insufficient	Player balance is insufficient
`G40001`	Third-party service exception	Third-party service exception

Integration checks

Confirm these controls in the final project protocol and test them before moving to production. This public page does not state that the server has already enabled them.

✓
Requests are traceable and logs are minimal: generate a unique reqTraceId for every call. Retain only the time, result code and redacted identifiers needed for diagnosis; do not log keys, full signatures, tokens, player details or full transaction payloads.
✓
Signatures are reproducible: signing input exactly matches the JSON string sent, and test cases cover C10004.
✓
Replay rules are explicit: confirm the allowed timestamp skew, nonce uniqueness and duplicate-request rejection rules, then test expired, reused and concurrent requests.
✓
Authorization and resource limits are explicit: enforce merchant-level access to endpoints, wallets and data, and confirm rate, concurrency, pagination and transaction limits together with alerting.
✓
Transactions are idempotent: deduplicate wallet notifications and transfers by transaction identifier so repeated requests do not create duplicate accounting.
✓
Results are reconcilable: for timeouts or network exceptions, query the transaction result before deciding whether to retry.
✓
Amounts use fixed-point values: do not use binary floating-point numbers for balances, bet amounts or payouts.

AG Game Open Platform API

Minimal request example

Authentication and signing

Common request headers

Signing string

Common response

Catalog and representative endpoints

Game catalog and sessions

Single-wallet callbacks

Transfer wallet

Records and merchant

POST/game/v5/game/urlCreate game session

Request fields

Response data

POST{MERCHANT-URL}/wallet/winWallet settlement callback

Request fields

POST/game/v5/cash/depositTransfer funds into game wallet

Request fields

POST/game/v5/game/recordQuery game records

Request fields

Technical FAQ

How does AG API generate a request signature?

Why is C10004 returned?

What is the difference between single wallet and transfer wallet?

How should repeated wallet callbacks be handled?

Can a transfer request be retried directly after a timeout?

What are reqTraceId and merchantTransactionId used for?

How is a player game session created?

How are player game records queried?

Error codes

Integration checks

Contact us

POST`/game/v5/game/url`Create game session

POST`{MERCHANT-URL}/wallet/win`Wallet settlement callback

POST`/game/v5/cash/deposit`Transfer funds into game wallet

POST`/game/v5/game/record`Query game records