---
url: /en/guide/conventions.md
---
# 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](./errors) is returned.
* Fields whose value is `false`, `0` or 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`.