归集开放平台

快速开始 ​

使用租户的 appID 和密钥，由你的服务端获取 accessToken，再调用开放接口。平台记录每笔已确认到账并发送通知；业务订单由你的系统关联。

接入准备 ​

项目说明
API 域名由平台单独提供；按本文档路径调用
链与网络TRON；核对平台为你开通的资产网络，并检查响应 network
appID、密钥由平台开通租户后提供，在你的服务端安全保存
运行环境示例支持 Node.js 22.12.0 或 Python 3.9+
回调地址通过设置回调配置保存并开启，使用公网HTTPS、443端口

服务端接入

从你的服务端调用平台提供的 HTTPS API 域名及 /open/v1 路径。密钥和 accessToken 不放入浏览器或移动客户端。

1. 获取令牌并查询钱包 ​

下载 Node.js 客户端 或 Python 客户端，放入你自己的示例目录。两份客户端的请求签名均只使用标准库。

设置服务端环境变量：

bash
# 先在运行环境中设置 GUIJI_BASE_URL，值为平台提供的 API 域名（不含 /open/v1）。
: "${GUIJI_BASE_URL:?请先设置平台提供的 API 域名}"
export GUIJI_APP_ID='YOUR_APP_ID'
export GUIJI_APP_SECRET='YOUR_APP_SECRET'

运行完整的「获取令牌 → 查询第一页钱包」流程：

bash
node client.mjs wallets
bash
python3 client.py wallets

脚本打印钱包查询结果，不打印密钥或 accessToken。底层会依次调用：

  1. POST /open/v1/auth/token：空请求体，以 appID、密钥、秒级时间戳计算签名。
  2. GET /open/v1/wallets?page=1&page_size=20：携带 Bearer accessToken，并对本次请求计算新签名。

一个租户只保留一个当前令牌

上面的独立演示每次运行都会获取新令牌，使该租户此前的令牌失效。实际系统应由一个共享令牌管理器获取和缓存令牌，各业务实例复用，不能每调用一次业务接口就重新获取。

2. 创建一个收款钱包 ​

将用户或业务对象关联到 custom_id。它最多 32 个字符，同一租户内唯一。创建请求还需要一个由你的服务端生成并保存的 request_id。

下面是完整的独立演示：读取环境变量 → 获取一次令牌 → 创建钱包。它会替换旧令牌，正式系统请复用共享缓存的令牌。沿用第1步的环境变量，另设置并保存本次业务编号：

bash
export GUIJI_CUSTOM_ID='customer-1001'
export GUIJI_REQUEST_ID='wallet-customer-1001-request-0001'
js
import { Client } from './client.mjs';

const customId = process.env.GUIJI_CUSTOM_ID;
const requestId = process.env.GUIJI_REQUEST_ID;
if (!customId || !requestId) throw new Error('请先设置并保存本次业务编号');
const client = new Client(
  process.env.GUIJI_BASE_URL,
  process.env.GUIJI_APP_ID,
  process.env.GUIJI_APP_SECRET
);
const { access_token } = await client.issueToken();
const wallet = await client.call(access_token, 'POST', '/open/v1/wallets', {}, {
  custom_id: customId,
  request_id: requestId
});
console.log(JSON.stringify(wallet, null, 2));
python
import json
import os
from client import Client

# 首次提交前将这两个值关联到你的业务并持久化。
custom_id = os.environ["GUIJI_CUSTOM_ID"]
request_id = os.environ["GUIJI_REQUEST_ID"]
client = Client(
    os.environ["GUIJI_BASE_URL"],
    os.environ["GUIJI_APP_ID"],
    os.environ["GUIJI_APP_SECRET"],
)
issued = client.issue_token()
wallet = client.call(issued["access_token"], "POST", "/open/v1/wallets", {}, {
    "custom_id": custom_id,
    "request_id": request_id,
})
print(json.dumps(wallet, ensure_ascii=False, indent=2))

将对应代码保存后，运行 node create-wallet.mjs 或 python3 create_wallet.py。超时重试必须保留原 request_id 和 custom_id；不能重新生成编号。新的独立业务才使用新编号。

收到结果后，把钱包 ID、地址与 custom_id 保存到你的业务系统。钱包 ID 始终作为字符串处理，不能转为 JavaScript Number。

3. 配置归集和回调 ​

使用相同accessToken和逐请求签名，按完整业务配置流程设置USDT归集地址、自动策略及Webhook。设置接口使用POST和JSON request_id，不需要MFA。

4. 接收到账通知 ​

通过回调配置API保存你的接收地址。平台发现指定代币的已确认到账后，会生成独立到账事件并推送。

你的接收程序按以下顺序处理：

  1. 使用 appID、密钥派生解密密钥，验证 AES-GCM 认证标签并解密。
  2. 校验明文 event_id 与外层事件 ID 一致。
  3. 将事件 ID 去重记录与业务处理结果在同一数据库事务中提交。
  4. 提交成功后返回 HTTP 200 和 {"code":"SUCCESS"}。

回调协议与可运行接收服务提供 Node.js、Python 示例，包含 SQLite 持久化去重、重启后去重和业务事务回滚。

5. 查询与对账 ​

未及时收到回调时，可以调用到账列表及到账详情接口核对。到账成功与通知成功相互独立，回调失败不会撤销到账记录。

金额统一使用六位精度的最小单位整数字符串：

接口金额展示金额
"100000000"100 USDT
"1020000"1.02 USDT
"1000000"1 TRX

不要用浮点数计算资产金额；Node.js 可以使用 BigInt，Python 可以使用整数。序列化回请求 JSON 时再转成字符串。

接下来 ​