XAgent Single Wallet Mode Access Document Manual V3.0

Preface

Connection Process

1. Provide relevant information and contact us to open an account for you in the UAT environment
2. Provide your server IP to add the server IP whitelist.
3. If your interface also has a whitelist, we will provide the server IP to add the whitelist to access your interface.
4. After the account is opened, we provide other parameters such as publicKey, logo, site, and the game background address
5. According to your game requirements, we provide the corresponding game coding table for docking
6. According to the document, you need to develop the interfaces we need and provide them
7. According to the game coding table, create game-related data (name, code, cover material, etc.) on your platform
8. Start docking the interface through the interface document
9. The interface docking is completed and the joint debugging test is correct
10. The formal environment is ready for access, and our business intervenes to discuss business matters with you
11. The formal environment account is opened, and the interface address and parameters are switched
12. You provide an IP whitelist, and the game background configures the whitelist
13. Pre-operation and acceptance of the formal environment
14. Access is completed and officially launched

Docking instructions

1. All our interface parameters are case-sensitive (case will not be ignored), please pay attention to the value

2. For all the interface parameters you provide, they also need to be case-sensitive (case will not be ignored)

3. After configuring the game entrance on your WEB / H5 / APP platform, the user clicks on the game entrance and calls the user registration/login interface provided by us

4. After success, get the interface return value, where webUrl and h5Url are the links carrying the user's login token

5. Go to the end of these two URLs and splice the game code (gameCode, see the return value interpretation of the registration/login interface for specific rules) provided by us to jump into the game body

6. You need to take the user's unique ID as userName, splice it according to certain rules, and pass it to the interface

7. If you need to get the trial entrance of the game, pass true for demoUser in the interface parameters.

8. We will call the interface you provide in different scenes in the game to increase, reduce assets, and query assets

9. You can create different proxy lines in the game console (backstage) provided by us. Each line can be configured with an independent RTP configuration, and the users of each line are also separated and independent.

10. When we open an account for you, we will help you create a default proxy line for your use. If you need more later, you can go to the backend to add them yourself.

11. You can also create your sub-agent in the backend, assign different proxy lines to your sub-agent management, and attach the sub-agent backend, which can view the relevant game data, user order records, reports, adjust RTP parameters, etc. assigned to the sub-agent.

Whitelist restrictions

Our interface domain name and the game backend we opened for you have set IP whitelist restrictions. If not configured, you cannot call the interface/access the backend. Therefore, before the docking starts, you need to provide the following IP information for us to pre-configure:

1. The IP address of the server in each environment

2. The IP address of the device you need to access the game backend

At the same time, if your interface is also set with whitelist restrictions, before calling the interface you provided, we will also provide you with the IP of the server in each environment for pre-configuration to ensure a smooth docking process

Interfaces provided by us

Domain name

UAT environment: https://xagent-open-api-uat.ncfc.cc

Formal environment: Contact business personnel to obtain

Preparation before calling

Headers：

Parameter encryption example:

//Parameters
Map<String, String> param = new HashMap<>();
param.put("account", "username");
param.put("password", "password");
//rsa encryption
byte[] encodedData = RSAUtil.encrypt(JSON.toJSONString(param).getBytes(), publicKey);
//base64
String base64String = Base64Util.encode(encodedData);
System.out.println("encoded: " + base64String);
Map<String, String> encryptParam = new HashMap<>();
encryptParam.put("data",base64String);
//Call interface httpPost(encryptParam);

// Param
$param = array(
    "account" => "username",
    "password" => "password"
);

// JSON Encode
$jsonData = json_encode($param);

// RSA Encrypt
$publicKey = "your-public-key"; // Replace your public key
$publicKeyResource = openssl_pkey_get_public($publicKey);
openssl_public_encrypt($jsonData, $encryptedData, $publicKeyResource);

// Base64 Encode
$base64String = base64_encode($encryptedData);
echo "encoded: " . $base64String . "\n";

// Build Request Param
$encryptParam = array(
    "data" => $base64String
);

// Call API
$response = httpPost($encryptParam);
echo $response;

// HTTP POST
function httpPost($params) {
    $url = 'your-api-endpoint'; // replace api address

    $options = array(
        'http' => array(
            'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
            'method'  => 'POST',
            'content' => http_build_query($params),
        ),
    );

    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);

    return $result;
}

import json
import base64
import requests
from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_OAEP

# param
param = {
    "account": "username",
    "password": "password"
}

# JSON encode
json_data = json.dumps(param)

# RSA Encrypt
public_key = 
"
-----BEGIN PUBLIC KEY-----
your-public-key-here
-----END PUBLIC KEY-----
"
rsa_key = RSA.import_key(public_key)
cipher = PKCS1_OAEP.new(rsa_key)
encoded_data = cipher.encrypt(json_data.encode('utf-8'))

# Base64 encode
base64_string = base64.b64encode(encoded_data).decode('utf-8')
print("encoded:", base64_string)

# build request param
encrypt_param = {
    "data": base64_string
}

# call api
response = requests.post('your-api-endpoint', data=encrypt_param)
print(response.text)

package main

import (
    "bytes"
    "crypto/rand"
    "crypto/rsa"
    "crypto/x509"
    "encoding/base64"
    "encoding/json"
    "encoding/pem"
    "fmt"
    "net/http"
)

func main() {
    // param
    param := map[string]string{
        "account":  "username",
        "password": "password",
    }

    // JSON encode
    jsonData, err := json.Marshal(param)
    if err != nil {
        fmt.Println("JSON Marshal error:", err)
        return
    }

    // RSA encrypt
    publicKey := `-----BEGIN PUBLIC KEY-----
your-public-key-here
-----END PUBLIC KEY-----`

    encodedData, err := rsaEncrypt(jsonData, publicKey)
    if err != nil {
        fmt.Println("RSA Encryption error:", err)
        return
    }

    // Base64 encode
    base64String := base64.StdEncoding.EncodeToString(encodedData)
    fmt.Println("encoded:", base64String)

    // build request param
    encryptParam := map[string]string{
        "data": base64String,
    }

    // call api
    response, err := httpPost("your-api-endpoint", encryptParam)
    if err != nil {
        fmt.Println("HTTP Post error:", err)
        return
    }

    fmt.Println("Response:", response)
}

const crypto = require('crypto');
const axios = require('axios');

// param
const param = {
    account: 'username',
    password: 'password'
};

// JSON encode
const jsonData = JSON.stringify(param);

// RSA encrypt
const publicKey = `-----BEGIN PUBLIC KEY-----
your-public-key-here
-----END PUBLIC KEY-----`;
const buffer = Buffer.from(jsonData, 'utf8');
const encryptedData = crypto.publicEncrypt(publicKey, buffer);

// Base64 encode
const base64String = encryptedData.toString('base64');
console.log("encoded: " + base64String);

// build request param
const encryptParam = {
    data: base64String
};

// call api
axios.post('your-api-endpoint', encryptParam)
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

1. API request method: application/json.
2. You need to add the two fixed values provided by us to the request header, the header key is site and businessAccount
3. You need to use the public key (publicKey) to perform RSA encryption on the request body, then convert the encrypted byte array into a Base64 string, and finally assemble it into {"data":"Encrypted Base64 string"} json format is submitted to the interface
4. In the http return object, code is the return code 200=normal, and the data is in data. When code is not 200, message is the error message.
5. Request example
6. Example XAgent server domain name is https://xagent-open-api-uat.ncfc.cc
7. The address of a certain interface is /v3/single/act
8. The merchant end public key is MIGfMA0GCSqGSIb3DQEBAQUAA4GNADC...
9. Business parameter json data {"field_1":"value_1","field_2":"value_2"}
10. First encrypt the business parameter with RSA to get the ciphertext Os977UOvhnqN+0xY4YBg95vlBpaKmgWAHnTa...
11. Set the request header businessAccount site content-type
12. After encoding the ciphertext in base64, build a unified request parameter entity {"data":"Os977UOvhnqN+0xY4YBg95vlBpaKmgWAHnTa..."}
13. Use post submission method to request https://xagent-open-api-uat.ncfc.cc/v3/single/act
14. Get response data {"code":200,"message":"success","data":{"field_a":"value_a","field_b":"value_b"}}
15. Determine whether the code is 200. If it is 200, it is strongly recommended that the merchant verify the response data. If it is not 200, there will be no signature value. The signature value is obtained from the response header signature
16. Concatenate the data in the Body with the public key to obtain {"code":200,"message":"success","data":{"field_a":"value_a","field_b":"value_b"}}MIGfMA0GCSqGSIb3DQEBAQUAA4GNADC...
17. Obtain the information summary of the concatenated string through the MD5 algorithm, and then compare it with the signature value in the response header. If they are consistent, the response data is safe
18. Then make subsequent business logic judgments based on business parameters

User registration / login (game entry)

Interface path

POST /v3/single/user/login

Interface description

Request this interface to register/login a user, and at the same time obtain the URL entry with the user token. The account must be unique.

Request parameters

Body:

Return data

data data:

Get historical bets

Interface path

POST /v3/single/bet/betting

Interface description

Interface for querying historical game bets (A maximum of 5,000 pieces of data can be returned in one call)

Request parameters

Body:

Return data

data data:

BetItemModel:

Get the game list

Interface path

POST /v3/single/game/list-gamecode

Interface description

Interface for getting the game list

Request parameters

Body:

Return data

Get a list of game categories

Interface path

POST /v3/single/game/list-gametype

Interface description

Interface for getting a list of game categories

Request parameters

Body:

Return data

Member Kickout Interface(PG Venus)

Interface Path

POST /v3/single/game/pgKickOut

Interface Description

PG game-specific, kick-off member offline interface, after calling, the member will be forced offline

Request Parameters

Body:

Return Data

View order details (PG Venus)

Interface path

POST /v3/single/game/pgSnapshot

Interface description

PG game only, you can view the detailed game screenshot details of a certain member's PG game order. After calling the interface, it is returned in the form of a URL, and you can view it directly by visiting

Request parameters

Body:

Return data

Interfaces and requirements you need to provide

Access preparation and instructions

Request parameter example

Unified request data structure:

{
"merchant":"The unique ID of the general agent provided by us",
"data":"The parameter of a specific interface is a json string and RSA encrypted",
"sign":"The encrypted signature data after decryption is data + merchant + timestamp",
"timestamp":"Request timestamp (millisecond level)"
}

Before making a request, we will assemble the parameters according to the parameters required by different interfaces, then serialize the parameter object into json, assign it to the data field, and then assemble it into the sign field to initiate a request to you.

Sign field assembly rules: In the body data structure, [all fields except sign] are sorted from small to large by field name, the values ​​are concatenated, RSA encrypted using publicKey, and then base64 encoded.

Data field encryption rules: decrypt according to the RSA public key

For example:

merchant="aaaa"

data="{\"field_1\":\"value_1\",\"field_2\":2}"

timestamp=12345678

Then the source string of the signature is:

"{\"field_1\":\"value_1\",\"field_2\":2}aaaa12345678"

Then use publicKey to rsa encrypt this data, and then base64 encode it to get the sign field

Return parameter example

The response parameter you need to package is data in Json format. The response Json data template is as follows:

Uniform response data structure:

{
"code": 200,
"message":"error message",
"data":"The parameter of a specific interface is a json string. It is returned directly without encryption"
}

Note: Here you also need to assemble and package a parameter into the responseHeader. The specific rules are as follows:

responseHeader

Key: signature

value: the JSON of the return result you packaged + publicKey and then MD5 encrypted

After getting the response, we will first determine whether the code is 200 success, and then obtain the data field data

Overall process:

a) We will use privateKey to encrypt the data, place it in the data and sign fields, and pass it to your interface

b) In the interface, you receive the data and sign parameters passed by us. You must first perform base64 decoding, and then use the RSA decryption tool to decrypt sign and data according to the publicKey provided by us

c) After decrypting sign, you get the merchant, data, and timestamp parameters,

d) Compare these three parameters with the merchant, data (requires base64 decoding + RSA decryption), and timestamp fields passed by us. If the results are consistent, the verification is passed.

e) The specific parameters passed by us are packaged in data, and the data can be used directly.

f) When you package your interface return value, the data field does not need to be encrypted, and the original value can be returned directly.

g) After the return value is assembled, according to the packaged return value, the signature field is placed in the responseHeader to return the response.

1. Before this API version is connected, we will provide you with a copy of the general agent unique identifier and publicKey, privateKey
2. Here is the description of what you need to prepare for us to call your interface
3. Request method: POST
4. Request parameters: The format is json, content-type=application/json
5. The following interface and description only show the data required by the data field

1. Get player information interface (/getaccountinfo)

• This interface is the game party's real-time query player balance interface

• Request parameters

• Response parameters

2. Bet application (/applycreatebet)

• This interface is called when the player places an order or pre-orders

• Request parameters

• Response parameters

3. Get bet information (/getbet)

• Request parameters

• Response parameters

4. Update the initial bet (/updatebet)

• Must be the initial bet
• Merchants who do not meet the requirements can reject the request and return the corresponding processing result

• Explanation of the meaning of the initial order: after a successful bet is placed, a bet will enter the next final state, and will eventually be either cancelled or settled that is, the initial bet is a bet with a valid order status and unsettled (betState==1 && settlementState==1)

• Request parameters

• Response parameters

5. Cancel initial bet (/cannelbet)

• Must be the initial bet

• Merchants who do not meet the conditions can reject and return the corresponding processing results

• Request parameters

• Response parameters

For the relationship between bets and bills, please refer to the introduction in the Appendix

6. Roll back canceled bets (/backcancelbet)

• Return the bet state to the canceled bet (betState=4) to the initial state
• It is equivalent to placing a new order, but the bet data is still the original

• The merchant side that does not meet the situation can refuse and return the corresponding processing result

• Request parameters

• Response parameters

7. Settlement of initial bets (/settlementbet)

• The betting and settlement process of different game halls or different types of bets is different
• 1. Call the betting interface first, then call the settlement interface
• 2. Directly give the settled bet, which is equivalent to calling the interface once to complete the betting and settlement

• The merchant end that does not meet the situation can refuse and return the corresponding processing result

• Request parameters

• Response parameters

8. Resettlement bet (/resettlementbet)

• Ignore the last settlement result and settle again according to the new settlement result
• Normally, if a merchant receives a request for resettlement, it needs to cancel the original settlement result and then settle according to the resettlement result. If the bet in the merchant system has not been settled before, the cancellation operation is ignored. The final decision is based on the merchant's system design

• Merchants that do not meet the situation can reject and return the corresponding processing result

• Request parameters

• Response parameters

9. Rollback settled bets (/backsettlementbet)

• Roll back settled bets (betState=1 && settlementState=3/4/5) to the initial state
• Normally, if the bet is a win, At this time, the rollback should return the settled net win or loss, of course, it will be determined by the merchant's system design
• It must be a settled bet (win/lose/draw)

• The merchant can reject if the situation is not met and return the corresponding processing result

• Request parameters

• Response parameters

10. Cancel settled bets (/cancelsettlementbet)

• Cancel settled bets directly, i.e. change betState from 1 to 4

• Normally, the merchant returns the balance according to the design of its own system

• Must be a settled bet

• Merchants that do not meet the conditions can reject and return the corresponding processing results

• Request parameters

• Response parameters

11. Balance adjustment (/adjustbill)

• For the game hall's event payout, there is no bet data, so the data will be pushed to the merchant system through this interface

• When betting/settling in some game halls, there are multiple bets in one round, but in the end it is also considered a bet, and this interface is also used to deduct or increase the balance

• This interface can also be called adding bills

• Request parameters

• Response parameters

12. Cancel bill (/cancelbill)

• Cancel the bill generated by the adjustbill interface through the venue's bill number. The merchant needs to roll back the addition or deduction in the bill and set the bill status to "invalid"

• If the bill is successfully canceled/does not exist/is already "invalid", the merchant needs to return the corresponding processing result

• Request parameters

• Response parameters

Appendix

ApplyCreateBetItemV3Model Single wallet betting model

SettlementBetItemV3Model Single wallet settlement bet model

GetBetItemV3Model Single wallet gets bet model

Special instructions on the amount appearing in the bet information

• BetAmount Bet amount can only be positive (greater than 0)
• PrizeAmount Prize amount includes the bet amount, and will not be negative in any case
• NetWinningAmount Net win/loss The final win/loss minus the bet amount, both positive and negative numbers are possible. If the net win/loss is negative, its absolute value must be less than or equal to the bet amount
• Bet 10 yuan, no prize: BetAmount=10; PrizeAmount=0; NetWinningAmount=-10;
• Bet 10, win 8: BetAmount=10; PrizeAmount=8; NetWinningAmount=-2;
• Bet 10, win 10: BetAmount=10; PrizeAmount=10; NetWinningAmount=0;

• Bet 10, win 14: BetAmount=10; PrizeAmount=14; NetWinningAmount=4;

  These three amounts must satisfy the identity BetAmount = PrizeAmount - NetWinningAmount;

• Due to the differences in different game hall interfaces, not all three fields will have values ​​every time during settlement, but they will be provided to merchants according to the conditions defined in this formula for settlement. For example, if SettlementAmountType specifies the use of PrizeAmount for settlement, then PrizeAmount can be used for settlement. Don't worry about the value of NetWinningAmount.

  For merchant settlement, PrizeAmount and NetWinningAmount can be used to complete the settlement.

• For bets that are placed first and settled later, that is, the betting amount has been deducted when the bet is placed, the settlement at this time is just to return the balance according to the winning situation.

  1. Calculated by PrizeAmount: Return amount = PrizeAmount, if it is greater than 0, increase the balance, otherwise it must be 0
  2. Calculated by NetWinningAmount: Return amount = BetAmount + NetWinningAmount, if it is greater than 0, increase the balance, otherwise it must be 0

• For bets placed and settled at the same time, BetAmount has a value, and PrizeAmount and NetWinningAmount must have one or both values.

  This depends on how the merchant keeps accounts. If one deduction and one addition are made, there is no difference from placing a bet first and then settling.

  • If it is recorded as one (may be an increase or a decrease)
  • There is definitely no difference in the bet amount, but the final addition and subtraction is a little different.

  1. Calculated by PrizeAmount: Final addition and subtraction = PrizeAmount - BetAmount, if it is greater than 0, the balance is increased, if it is less than 0, it is reduced, and there is also a case of 0
  2. Calculated by NetWinningAmount: Final addition and subtraction = NetWinningAmount, if it is greater than 0, the balance is increased, if it is less than 0, it is reduced, and there is also a case of 0

Remember that these three amounts must satisfy the identity BetAmount = PrizeAmount - NetWinningAmount. Only those that satisfy this equation are correct.

SingleBetItemV3Result Single wallet bet processing result model

• About the relationship and difference between bets and bills:
• Bet is the player's game record, while bill is a financial record.
• Most venues are designed without bills. Only some venues will place multiple bets in one game, and there will be multiple bills, but in the end there will be only one bet information. Merchants only need to dock and callback according to the requirements of this document.
• For those who only have bills but no betting hall, if the merchant needs betting data, he can call the single wallet mode to obtain the historical betting interface to obtain the player's historical betting records

BrandBetItemExtend Detailed data of chess and card betting

ElectronicBetItemExtend Detailed data of electronic entertainment betting

LiveBetItemExtend Detailed data of live betting

LotteryBetItemExtend Detailed data of lottery betting

SportBetItemExtend Detailed data of sports betting

StockBetItemExtend stock betting details

SportBetItemDetail Specific match information entity of sports betting

SingleBillItemV3Model Single Wallet Bill Model

SingleBillItemV3Result Single wallet bill processing result model

GameType

Only some GameTypes are shown here for reference only. For details, please check the XAgent Game List document. Subsequent additions will be reflected in the document, or View the latest data through the merchant backend

Coin currency

The subsequent addition will be reflected in the document, or you can check the latest data through the merchant backend

Lang language

Added later will be reflected in the document, or check the latest data through the merchant backend

BetOperateStates bet processing results

BillOperateStates bill processing results

VenueResultCodes Common error codes

• 3*** series are XAgent related error codes
• 5*** series are game hall related error codes
• 7*** series are error codes returned for some specific scenarios of the merchant callback interface. When the merchant handles the callback, it can return the corresponding error code according to the actual situation
• Other error codes are general error codes, such as 200/9999

BetStates Bet state

• The bet status of a single wallet has only two states: valid and canceled
• The unknown state will only appear when it is unavailable or the acquisition is wrong, and it will not appear normally

GameTypeList Game category entity

GameCodeList Game list entity