Agent Request API
Reference for agent integration, transfers, and account operations.
Getting started
Technical field names and example payloads are preserved from the source.
appid:123457945payPassward:125678Authentication & 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
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 codeCopy 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.
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
- Build the required user-verification parameters, including a current Unix timestamp in seconds.
- UTF-8 encode the chosen plaintext and encrypt with RSA PKCS#1 v1.5 using the supplied public key.
- 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.
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) }
}
import { readFileSync } from 'node:fs';
import { createPublicKey, publicEncrypt, constants } from 'node:crypto';
const APP_ID = 123457945;
const USER_ID = 123457947;
// The documented PEM label is inconsistent with its SPKI DER content.
// Decode the base64 and explicitly import as SPKI (Node.js 18+).
const keyBase64 = readFileSync('public_key.pem', 'utf8')
.replace(/-----[^-]+-----/g, '')
.replace(/\s+/g, '');
const publicKey = createPublicKey({
key: Buffer.from(keyBase64, 'base64'), format: 'der', type: 'spki',
});
const params = {
app_id: APP_ID,
request_time: Math.floor(Date.now() / 1000),
user_id: USER_ID,
};
// ASSUMPTION: compact JSON is encrypted and Base64 is sent in the sign header.
const plaintext = Buffer.from(JSON.stringify(params), 'utf8');
const ciphertext = publicEncrypt(
{ key: publicKey, padding: constants.RSA_PKCS1_PADDING }, plaintext,
);
const sign = ciphertext.toString('base64');
const baseURL = (process.env.AGENT_API_BASE_URL || 'https://test-h5.hzshtech.cn/api')
.replace(/\/$/, '');
const res = await fetch(`${baseURL}/agent/api/check-user`, {
method: 'POST',
headers: {
appid: String(APP_ID),
sign,
'Content-Type': 'application/json',
},
// No request body per the source document.
});
console.log(`HTTP ${res.status}`);
console.log(await res.text());
import javax.crypto.Cipher;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.KeyFactory;
import java.security.PublicKey;
import java.security.spec.X509EncodedKeySpec;
import java.time.Duration;
import java.time.Instant;
import java.util.Base64;
import java.util.Locale;
public class AgentRequestExample {
private static final int APP_ID = 123457945;
private static final int USER_ID = 123457947;
public static void main(String[] args) throws Exception {
// The PEM label in the documentation is inconsistent with SPKI DER.
String pem = Files.readString(Path.of("public_key.pem"));
String clean = pem.replaceAll("-----[^-]+-----", "").replaceAll("\\s+", "");
byte[] der = Base64.getDecoder().decode(clean);
PublicKey key = KeyFactory.getInstance("RSA")
.generatePublic(new X509EncodedKeySpec(der));
// ASSUMPTION: encrypt compact JSON as UTF-8 with RSA PKCS#1 v1.5.
String params = String.format(Locale.ROOT,
"{\"app_id\":%d,\"request_time\":%d,\"user_id\":%d}",
APP_ID, Instant.now().getEpochSecond(), USER_ID);
Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
cipher.init(Cipher.ENCRYPT_MODE, key);
byte[] encrypted = cipher.doFinal(params.getBytes(StandardCharsets.UTF_8));
// ASSUMPTION: standard Base64 is accepted by the sign header.
String sign = Base64.getEncoder().encodeToString(encrypted);
String baseURL = System.getenv("AGENT_API_BASE_URL");
if (baseURL == null || baseURL.isBlank()) {
baseURL = "https://test-h5.hzshtech.cn/api";
}
String endpoint = baseURL.replaceAll("/+$", "") + "/agent/api/check-user";
HttpRequest request = HttpRequest.newBuilder(URI.create(endpoint))
.timeout(Duration.ofSeconds(15))
.header("appid", Integer.toString(APP_ID))
.header("sign", sign)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.noBody()) // No body.
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> res = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP " + res.statusCode());
System.out.println(res.body());
}
}
import base64
import json
import os
import time
from pathlib import Path
from urllib import request, error
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import padding
APP_ID = 123457945
USER_ID = 123457947
# Save the original test key as public_key.pem. Its label is misleading:
# the DER bytes inside are X.509 SubjectPublicKeyInfo (SPKI).
pem_text = Path('public_key.pem').read_text(encoding='utf-8')
key_b64 = ''.join(
line.strip() for line in pem_text.splitlines()
if line.strip() and not line.startswith('-----')
)
public_key = serialization.load_der_public_key(base64.b64decode(key_b64))
params = {
'app_id': APP_ID,
'request_time': int(time.time()),
'user_id': USER_ID,
}
# ASSUMPTION: the server encrypts compact JSON, not a query string.
plaintext = json.dumps(params, separators=(',', ':'), ensure_ascii=False).encode('utf-8')
ciphertext = public_key.encrypt(plaintext, padding.PKCS1v15())
# ASSUMPTION: standard Base64 encoded ciphertext is sent as sign.
sign = base64.b64encode(ciphertext).decode('ascii')
base_url = os.getenv('AGENT_API_BASE_URL', 'https://test-h5.hzshtech.cn/api')
url = base_url.rstrip('/') + '/agent/api/check-user'
req = request.Request(url, method='POST', headers={
'appid': str(APP_ID),
'sign': sign,
'Content-Type': 'application/json',
}) # No request body.
try:
with request.urlopen(req, timeout=15) as response:
print(f'HTTP {response.status}')
print(response.read().decode('utf-8'))
except error.HTTPError as exc:
print(f'HTTP {exc.code}')
print(exc.read().decode('utf-8', errors='replace'))
How to run
go run main.goThe 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
/agent/api/check-userRequest parameters
| Field | Type | Required | Description |
|---|---|---|---|
user_id | int | Required | User ID |
app_id | int | Required | App ID |
request_time | int | Required | request time,timestamp in seconds |
Response parameters
| Field | Type | Description |
|---|---|---|
user_id | int | User ID |
nickname | string | Nickname |
portrait | string | Avatar |
Response example
{
"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
/agent/api/transfer-recordRequest parameters
| Field | Type | Required | Description |
|---|---|---|---|
page | int | Required | Page number, starting from 0 |
size | int | Required | Number of records per page |
start_time | int | Optional | Start time, timestamp in seconds |
end_time | int | Optional | End time, timestamp in seconds |
target_user_id | int | Optional | Target user ID |
app_id | int | Required | App ID |
request_time | int | Required | request time,timestamp in seconds |
Response parameters
| Field | Type | Description |
|---|---|---|
order_id | int | order_id |
user_id | int | User id |
target_user_id | int | Platform order ID |
one_price | float | unit price |
cost_price | float | Cost unit price |
diamonds | int | amount |
before_change | int | Before balance |
after_change | int | After balance |
certificate_url | string | voucher |
payment_id | int | channel |
payment_name | string | channel name |
link_order_id | string | Your order id |
create_time | int | create time |
update_time | int | update time |
Response example
{
"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
/agent/api/transfer-diamondPlease call /agent/api/check-user before using, otherwise error 4005 will occur
Request parameters
| Field | Type | Required | Description |
|---|---|---|---|
target_user_id | int | Required | Target user ID |
app_id | int | Required | app_id |
diamonds | int | Required | diamonds |
pay_password | string | Required | pay password(Please refer to the following figure for details) |
link_order_id | string | Required | Your order id |
request_time | int | Required | request time,timestamp in seconds |
Response parameters
| Field | Type | Description |
|---|---|---|
remain_diamonds | int | Remaining Diamonds |
balance_money | int | Agent Balance |
order_id | Int | Platform order ID |
Response example
{
"code": 0,
"message": "success",
"data": {
"remain_diamonds": 51151144,
"balance_money": 119380500
}
}Payment password setup
Tap on "Payment Password" to set the payment password.
Reference screenshot from the original document
4.Account
Read the agent account balance
/agent/api/accountRequest parameters
| Field | Type | Required | Description |
|---|---|---|---|
app_id | int | Required | app_id |
request_time | int | Required | request time,timestamp in seconds |
Response parameters
| Field | Type | Description |
|---|---|---|
remain_diamonds | int | Remaining Diamonds |
balance_money | int | Agent Balance |
Response example
{
"code": 0,
"message": "success",
"data": {
"remain_diamonds": 51151144,
"balance_money": 119380500
}
}Status codes
Status codes returned by the API, as documented in the source.
| Code | Description |
|---|---|
0 | Success |
500 | Request Failed |
1000 | Parameter Error |
1001 | Request time difference of 60 seconds |
1053 | frequent operations |
4001 | IP Inaccessible |
4002 | Sign is Empty |
4003 | Unauthorized agent user |
4004 | Sign Error, Parsing Failed |
4005 | Operation Error, No Verification of Transfer User 10 Minutes Before Transfer |
4006 | Agent Account Exception |
4007 | Incorrect Payment Password |
4008 | Insufficient Balance |
4009 | Order Repeat |
4010 | Cannot 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.