Agent API / Docs
⌘ K
Integration guide

Agent Request API

Reference for agent integration, transfers, and account operations.

4 API endpointsPOST requestsAPI rate limit: 30s

Getting started

Technical field names and example payloads are preserved from the source.

Test environment
Production environment
Not provided in source document
Test AppIDappid:123457945
Test payPasswardpayPassward:125678
Test public key

Expand to view the public key supplied in the source document.

RSA PUBLIC KEY
-----BEGIN RSA PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxECrth+d5t2eCb8GBOXx
JXSdNOs8JiGtJPUWYwTgTQprFI4p+3I17udgRhOiv+yJc5CHB9ietXcsWpVk3245
LuFM6dCAMw1ioJTqyh2DEPYKrnj43nqpxkIg/SmCAPiisAEVGaGfuvf19TNp8LZm
hGmHAZu04/QjdeVZHhIwEkLklSxf5H6YGIjZrUHSPDotsvSWBd2fMMy3vqQnvIBJ
V4c0BLolBqAG7qMG5hsUt66Bl/7QXNthmXM7SPkpYsyfJq6m0lmq6jpHE6uACsJs
s2xDU50ZntgWpoAoE1vk/r+6XKGm9G6vqa9fEozDxGiEBhZxozGTrY7cEiInY1U7
7QIDAQAB
-----END RSA PUBLIC KEY-----

Authentication & signing

Request Method

Add appid and sign to the header.

appid is the agent user ID.

sign: The parameters are encrypted using the EncryptPKCS1v15 public key, and the parameters do not need to be hashed.

No need to put parameters in the body

Interface Request Limitations

One request per interface every 30 seconds

cURL example

BASH
curl -X POST http://localhost:8080/agent/api/check-user \
-H "Content-Type: application/json" \
-H "appid:<your appid>" \
-H "sign: <sign>" \

The original example uses localhost:8080. Update the host for your environment.

Signing & HTTP request examples

Illustrative integration code

Copy a full working-language example for user verification. Each snippet reads the test public key, encrypts the request parameters, adds appid and sign headers, and sends POST without a body.

Important: protocol details need confirmation

The source specifies public-key RSA PKCS#1 v1.5 encryption but does not define parameter serialization, sign header encoding, or test URL concatenation. These samples ASSUME compact JSON, standard Base64, and test base URL + API path. Confirm these with your backend before using the examples in production.

Example workflow

  1. Build the required user-verification parameters, including a current Unix timestamp in seconds.
  2. UTF-8 encode the chosen plaintext and encrypt with RSA PKCS#1 v1.5 using the supplied public key.
  3. Encode ciphertext for the sign header; send appid and sign with a POST request (no body).

Save the public key shown above as public_key.pem in the same folder as the sample code (the ZIP includes it). Its PEM label is inconsistent with its SPKI contents; the examples handle this explicitly.

main.go
package main

import (
    "crypto/rand"
    "crypto/rsa"
    "crypto/x509"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "strings"
    "time"
)

const (
    appID  = 123457945
    userID = 123457947
)

type Params struct {
    AppID       int   `json:"app_id"`
    RequestTime int64 `json:"request_time"`
    UserID      int   `json:"user_id"`
}

func main() {
    // Save the test key from the documentation as public_key.pem.
    // Its label says "RSA PUBLIC KEY" but its content is SPKI DER.
    text, err := os.ReadFile("public_key.pem")
    check(err)
    var lines []string
    for _, line := range strings.Split(string(text), "\n") {
        line = strings.TrimSpace(line)
        if line != "" && !strings.HasPrefix(line, "-----") {
            lines = append(lines, line)
        }
    }
    der, err := base64.StdEncoding.DecodeString(strings.Join(lines, ""))
    check(err)
    anyKey, err := x509.ParsePKIXPublicKey(der)
    check(err)
    publicKey, ok := anyKey.(*rsa.PublicKey)
    if !ok { panic("not an RSA public key") }

    params := Params{AppID: appID, RequestTime: time.Now().Unix(), UserID: userID}
    // ASSUMPTION: compact JSON bytes are the plaintext for RSA encryption.
    payload, err := json.Marshal(params)
    check(err)
    ciphertext, err := rsa.EncryptPKCS1v15(rand.Reader, publicKey, payload)
    check(err)
    // ASSUMPTION: the server expects standard Base64 in the sign header.
    sign := base64.StdEncoding.EncodeToString(ciphertext)

    baseURL := os.Getenv("AGENT_API_BASE_URL")
    if baseURL == "" { baseURL = "https://test-h5.hzshtech.cn/api" }
    url := strings.TrimRight(baseURL, "/") + "/agent/api/check-user"
    req, err := http.NewRequest(http.MethodPost, url, nil) // No request body.
    check(err)
    req.Header.Set("appid", strconv.Itoa(appID))
    req.Header.Set("sign", sign)
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 15 * time.Second}
    resp, err := client.Do(req)
    check(err)
    defer resp.Body.Close()
    body, err := io.ReadAll(resp.Body)
    check(err)
    fmt.Printf("HTTP %d\n%s\n", resp.StatusCode, body)
}

func check(err error) {
    if err != nil { panic(err) }
}

How to run

go run main.go

The base URL can be overridden with AGENT_API_BASE_URL. Default URL construction is an unverified assumption.

The examples implement public-key encryption, not a private-key digital signature. PKCS#1 v1.5 encryption has randomized ciphertext: different sign values for the same plaintext are normal.

Observe the source rate limit of 1 request / endpoint / 30 seconds; a request_time older than roughly 60 seconds may trigger status 1001.

Other endpoints: change the URL path and encrypt that endpoint’s required parameters; do not add them to the request body.

Code files, public key, and README are bundled with the ZIP download.

Endpoints

1.User Verification

Verify a user before transferring diamonds

POST
/agent/api/check-user

Request parameters

FieldTypeRequiredDescription
user_idintRequiredUser ID
app_idintRequiredApp ID
request_timeintRequiredrequest time,timestamp in seconds

Response parameters

FieldTypeDescription
user_idintUser ID
nicknamestringNickname
portraitstringAvatar

Response example

JSON
{
    "code": 0,
    "message": "success",
    "data": {
        "user_id": 123457947,
        "nickname": "sss",
        "portrait": "https://istatic.imamolive.top//common/fuya_def_head.png"
    }
}

2. Retrieve Transfer Records

Retrieve transfer history

POST
/agent/api/transfer-record

Request parameters

FieldTypeRequiredDescription
pageintRequiredPage number, starting from 0
sizeintRequiredNumber of records per page
start_timeintOptionalStart time, timestamp in seconds
end_timeintOptionalEnd time, timestamp in seconds
target_user_idintOptionalTarget user ID
app_idintRequiredApp ID
request_timeintRequiredrequest time,timestamp in seconds

Response parameters

FieldTypeDescription
order_idintorder_id
user_idintUser id
target_user_idintPlatform order ID
one_pricefloatunit price
cost_pricefloatCost unit price
diamondsintamount
before_changeintBefore balance
after_changeintAfter balance
certificate_urlstringvoucher
payment_idintchannel
payment_namestringchannel name
link_order_idstringYour order id
create_timeintcreate time
update_timeintupdate time

Response example

JSON
{
    "code": 0,
    "message": "success",
    "data": {
        "count": 1,
        "list": [
            {
                "order_id": 1850,
                "user_id": 123457945,
                "target_user_id": 123457947,
                "one_price": 0.28,
                "cost_price": 0.2740500025,
                "diamonds": 100000,
                "before_change": 999999799999,
                "after_change": 999999699999,
                "certificate_url": "",
                "payment_id": 0,
                "payment_name": "",
                "link_order_id": "oid123451678",
                "create_time": 1744615890,
                "update_time": 1744615890
            }
        ]
    }
}

3.Transfer

Transfer diamonds to a user

POST
/agent/api/transfer-diamond
Important prerequisite

Please call /agent/api/check-user before using, otherwise error 4005 will occur

Request parameters

FieldTypeRequiredDescription
target_user_idintRequiredTarget user ID
app_idintRequiredapp_id
diamondsintRequireddiamonds
pay_passwordstringRequiredpay password(Please refer to the following figure for details)
link_order_idstringRequiredYour order id
request_timeintRequiredrequest time,timestamp in seconds

Response parameters

FieldTypeDescription
remain_diamondsintRemaining Diamonds
balance_moneyintAgent Balance
order_idIntPlatform order ID

Response example

JSON
{
    "code": 0,
    "message": "success",
    "data": {
        "remain_diamonds": 51151144,
        "balance_money": 119380500
    }
}

Payment password setup

Tap on "Payment Password" to set the payment password.

Payment password setup screenshot

Reference screenshot from the original document

4.Account

Read the agent account balance

POST
/agent/api/account

Request parameters

FieldTypeRequiredDescription
app_idintRequiredapp_id
request_timeintRequiredrequest time,timestamp in seconds

Response parameters

FieldTypeDescription
remain_diamondsintRemaining Diamonds
balance_moneyintAgent Balance

Response example

JSON
{
    "code": 0,
    "message": "success",
    "data": {
        "remain_diamonds": 51151144,
        "balance_money": 119380500
    }
}

Status codes

Status codes returned by the API, as documented in the source.

CodeDescription
0Success
500Request Failed
1000Parameter Error
1001Request time difference of 60 seconds
1053frequent operations
4001IP Inaccessible
4002Sign is Empty
4003Unauthorized agent user
4004Sign Error, Parsing Failed
4005Operation Error, No Verification of Transfer User 10 Minutes Before Transfer
4006Agent Account Exception
4007Incorrect Payment Password
4008Insufficient Balance
4009Order Repeat
4010Cannot transfer funds across regions

Source documentation notes

  • The production environment URL is blank in the supplied documentation.
  • The original source provides no full signing implementation. See the illustrative language examples above; confirm the assumed serialization, encoding, and URL with the API owner before integration.
  • The original cURL example targets localhost:8080; it is preserved, not a production endpoint.
Agent Request API · Source data unchanged