Conventions
Requests and responses
- HTTPS only; request and response bodies are UTF-8 JSON.
- Field names are
snake_case. - On success the HTTP status is 200 and the body is the resource itself (no
{code, data}wrapper). On failure an error body is returned. - Fields whose value is
false,0or an empty string may be omitted from responses — treat them as the default. - New fields may be added; ignore fields you don't recognise.
Numbers and time
| Kind | Representation |
|---|---|
| Time | Unix milliseconds as a JSON string, e.g. "1762650000000"; 0 means "not yet" |
| int64 (IDs, block numbers, …) | JSON strings, to avoid JavaScript precision loss, e.g. "deposit_id": "1987654321098752" |
| Amounts | Both forms: amount is a decimal string in the main unit (e.g. "12.5"), amount_raw an integer string in the smallest unit (e.g. "12500000", together with decimals). Never use floating point for amounts |
Pagination
List endpoints use cursor pagination:
| Parameter / field | Description |
|---|---|
page_size | Items per page, default 20, max 100 (larger values are treated as 100) |
page_token | Omit for the first page; then pass the previous next_page_token |
next_page_token | Opaque string — pass it back unchanged; empty means no more pages |
Responses look like {"deposits": [...], "next_page_token": "..."}, with the plural resource name as the list field. Keep the other filters unchanged while paging.
Idempotency
| Endpoint | How |
|---|---|
POST /v1/wallets/{user_id}/addresses | Naturally idempotent — the same user and chain always get the same address |
POST /v1/withdraws | biz_id (your order number) is unique per merchant; a repeat returns 409 DUPLICATE_REQUEST with the existing withdrawal in metadata.withdrawId |
POST /v1/deposits/rescan | Already-detected deposits are never credited twice |
When the outcome is unknown (e.g. a network timeout), retry with the same biz_id or look it up with GET /v1/withdraws?biz_id= — never retry with a new order number.
Chain and token codes
Chain codes: TRON, ETH, BSC (authoritative list: GET /v1/chains). Token codes such as USDT; whether a token can be deposited / withdrawn on a chain, plus minimums and fees, come from GET /v1/assets.