---
url: /guide/conventions.md
---
# 通用约定

## 请求与响应

* 只用 HTTPS；请求体和响应体都是 JSON，UTF-8。
* 字段名一律 `snake_case`。
* 成功时 HTTP 200，**直接返回资源本身**（没有 `{code, data}` 外层包装）。失败时返回 [错误体](./errors)。
* 值为 `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` 为准。