归集开放平台

API 总览 ​

API 域名由平台单独提供，本文档只列接口路径。请求地址由该域名与接口路径组合；不要使用文档站域名代替 API 域名。公网接入使用 HTTPS。

平台记录每笔已确认到账，再通过回调通知三方。平台不创建或匹配支付订单。三方可使用 custom_id 关联自己的客户，使用固定到账事件 ID 去重，再关联自己的业务订单。

接口清单 ​

方法路径用途
POST/open/v1/auth/token获取 accessToken
GET/open/v1/dashboard账户概览
GET/open/v1/wallets钱包列表
POST/open/v1/wallets创建钱包
POST/open/v1/wallets/selection跨页选择钱包
GET/open/v1/wallets/{id}钱包详情
POST/open/v1/sweeps创建归集任务
GET/open/v1/sweeps归集列表
GET/open/v1/sweeps/{id}归集详情
GET/open/v1/deposits到账列表
GET/open/v1/deposits/{id}到账详情

设置、预估和通知接口 ​

方法路径用途
GET/open/v1/settings/addresses查询账户地址
POST/open/v1/settings/addresses/collection设置 USDT 归集地址
GET/open/v1/settings/automation查询自动归集配置
POST/open/v1/settings/automation设置自动归集
GET/open/v1/settings/webhook查询回调配置
POST/open/v1/settings/webhook设置回调配置
POST/open/v1/wallets/preview批量预览钱包
POST/open/v1/sweeps/estimate预估归集手续费
GET/open/v1/webhooks查询通知列表
GET/open/v1/webhooks/{id}查询通知详情
GET/open/v1/webhooks/{id}/rounds查询通知轮次
GET/open/v1/webhooks/{id}/attempts查询推送尝试
POST/open/v1/webhooks/{id}/redeliver重新推送异常通知

共 24 个 /open/v1 操作，另有无需鉴权的 GET /healthz 和 GET /openapi.json，合计 26 个操作。所有业务操作均使用本页说明的 accessToken 和请求签名。

鉴权与请求格式 ​

  • 换取令牌只需签名头；其请求体、Query、Authorization 必须为空。其余 23 个业务操作同时要求 Bearer accessToken 和逐请求签名。
  • 签名为 HMAC-SHA256，使用现有密钥，覆盖 HTTP 方法、路径、appID、时间戳、token、查询串和原始请求体摘要；输出64位小写十六进制。直接使用示例客户端，完整规则见请求签名。
  • GET 请求体必须为空。业务 POST 使用 UTF-8 JSON 对象；不接受重复 JSON 键、多个 JSON 值或顶层数组/null。
  • Query 不能重复键；其规范化与实际请求必须一致。所有 POST 接口均拒绝 Query（包括裸问号）；业务参数全部放 JSON，request_id 也只能放 JSON。
  • 所有接口只接受参数表中声明的字段；未知查询键、额外JSON顶层字段及未知filters字段直接返回400。
  • 不接受 Idempotency-Key，不接收明文 appSecret。调用所需租户由当前 appID 和 accessToken 决定。

数据类型 ​

类型约定
ID钱包、任务、到账、事件 ID 均为字符串，不能先转 JavaScript Number；示例 "123456789012345678"。
输入对象 ID正 int64 字符串，最大 9223372036854775807。原样使用接口返回的 ID，不增加前导零或 +；appID 也使用规范的正整数字符串。
金额USDT 与 TRX 都为六位精度的最小单位整数字符串："100000000" 是 100 USDT，"1000000" 是 1 TRX（1,000,000 SUN）。以整数计算，只在显示时格式化。
时间带时区的 RFC3339 字符串，可含小数秒；允许为空的字段明确返回 JSON null，不是空字符串。
空列表[]；不返回 null。
未配置地址 / 未保存哈希destination / txid 使用空字符串；不是 null。
余额最近一次同步的已确认余额，可能存在同步延迟。balance_block="0" 表示首次同步尚未完成，不能当作真实零余额。

所有示例 ID、地址、凭据及交易哈希均为文档合成值，不代表现有账户或可用测试资产。不要向示例地址转账。

成功和错误 ​

所有业务成功响应都是 HTTP 200，创建接口也不返回 201：

json
{
  "code": 0,
  "message": "",
  "data": {}
}

data 必须按各接口的具体字段解释，上面的空对象只展示外层格式。错误响应没有 data：

json
{
  "code": 401,
  "message": "authentication required or expired",
  "error_code": "TOKEN_INVALID_OR_EXPIRED",
  "trace_id": "0123456789abcdef0123456789abcdef"
}
字段类型必填说明示例值
codeinteger是成功为 0；错误与 HTTP 状态码一致。0
messagestring是成功为空字符串；错误为原因文本。""
data具体对象仅成功各接口响应表定义，不是任意对象。见接口页
HTTP含义message 示例
400参数或请求格式错误invalid request
401签名、时间窗口或令牌无效authentication required or expired
403租户停用、删除或过期tenant disabled or expired
404对象不存在，或不属于当前租户和网络not found
409幂等参数冲突，或唯一记录冲突conflict: idempotency key already used with another request
413请求体超过大小限制request body exceeds configured limit
429请求频率超限；读取 Retry-After 秒数too many requests
500内部依赖或业务执行失败internal operation failed
503请求繁忙；Retry-After 为 1 秒too many in-flight requests
504操作超过请求截止时间request timed out

错误正文的 message 可能因具体校验而不同，请按 HTTP 状态和 error_code 分类，并保留 message 与 trace_id。429 带 Retry-After 秒数；全局并发过载 503 的 Retry-After 为 1。具体限制见错误处理与限频。响应带 Cache-Control: no-store 和 X-Content-Type-Options: nosniff。

业务 API 的未知路径和错误请求方法也返回上述 JSON：404 对应 ROUTE_NOT_FOUND，405 对应 METHOD_NOT_ALLOWED。网关或代理可能返回非 JSON 错误，客户端应先判断 HTTP 状态和 Content-Type；不能把解析失败当作成功。

分页和幂等 ​

列表页 page 默认为 1，page_size 默认为 20，范围 1–100；不传或传空字符串使用默认值。超出最后一页时 items=[]，仍返回真实 total。钱包支持指定排序；归集和到账按 ID 降序。

创建钱包、创建归集任务、修改账户地址/自动策略/回调配置及重新推送通知必须带JSON request_id。只读POST的跨页选择、钱包预览、手续费预估不需要request_id。长度实际按 UTF-8 编码计为 16–128 字节，推荐使用 36 位 ASCII UUID，无需计算中文长度。同租户、同操作、同 request_id、同业务参数返回最初保存的成功响应；改变参数返回 409。JSON 键顺序不改变业务幂等结果，但会改变原始请求体签名，必须重新签名。

请求超时或连接中断后，应保留 request_id 和业务参数重试。最初成功响应是创建时的快照；后续状态通过详情接口查询。创建钱包/归集的业务校验失败后也可能已登记该request_id；修改参数应生成新编号。归集响应内单项 failed 也是已保存结果，修正条件后重新发起业务需用新 request_id。

机器可读契约 ​

下载本站完整 OpenAPI 3.1 文档。这份静态契约对应以上 26 个操作。外部服务自身的 GET /openapi.json 与本站下载提供同一份完整规范，可优先使用本站下载文件。

完整顺序见业务配置流程：创建钱包 → 设置归集目标 → 自动策略 → Webhook。

金额、ID 和资产网络的解释见通用约定。