通用约定
请求与响应
- 只用 HTTPS；请求体和响应体都是 JSON，UTF-8。
- 字段名一律
snake_case。 - 成功时 HTTP 200，直接返回资源本身（没有
{code, data}外层包装）。失败时返回 错误体。 - 值为
false、0、空串的字段可能不出现在响应里，请按默认值处理。 - 以后可能新增字段，请忽略不认识的字段。
数值与时间
| 类型 | 表示 |
|---|---|
| 时间 | Unix 毫秒，JSON 字符串，如 "1762650000000"；0 表示「还没有」 |
| int64（ID、区块号等） | JSON 字符串，避免 JavaScript 精度丢失，如 "deposit_id": "1987654321098752" |
| 金额 | 同时给两种：amount 为主单位十进制字符串（如 "12.5"），amount_raw 为最小单位整数字符串（如 "12500000"，配合 decimals）。不要用浮点数计算金额 |
分页
列表接口使用游标分页：
| 参数 / 字段 | 说明 |
|---|---|
page_size | 每页条数，默认 20，最大 100（超过按 100） |
page_token | 第一页不传；之后传上一页返回的 next_page_token |
next_page_token | 不透明字符串，原样回传；为空表示没有更多 |
响应形如 {"deposits": [...], "next_page_token": "..."}，列表字段名是资源复数。翻页时其它筛选参数要保持不变。
幂等
| 接口 | 幂等方式 |
|---|---|
POST /v1/wallets/{user_id}/addresses | 天然幂等，同一用户同一条链永远返回同一地址 |
POST /v1/withdraws | biz_id（你的订单号）在商户内唯一；重复提交返回 409 DUPLICATE_REQUEST，metadata.withdrawId 为已存在的提现单 |
POST /v1/deposits/rescan | 已识别的充值不会重复入账 |
网络超时等无法确定结果时，用同一个 biz_id 重试，或用 GET /v1/withdraws?biz_id= 查询，不要换新单号重试。
链与币种代码
链代码：TRON、ETH、BSC（以 GET /v1/chains 返回的为准）。币种代码如 USDT；某个币种在某条链上是否可充可提、最小额与手续费以 GET /v1/assets 为准。