---
url: /en/reference/deposits.md
---
# Deposits

Deposit records and rescans

## List deposits

```http
GET /v1/deposits
```

API key scope: `read`

List deposits: ordered by deposit_id descending, cursor pagination

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `user_id` | query | string | no | User ID: optional |
| `chain_code` | query | string | no | Chain code: optional |
| `token_code` | query | string | no | Token code: optional |
| `status` | query | string | no | Status: optional |
| `tx_hash` | query | string | no | Transaction hash: optional |
| `start_time` | query | string | no | Start time: by detection time, Unix milliseconds, inclusive |
| `end_time` | query | string | no | End time: by detection time, Unix milliseconds, inclusive |
| `page_size` | query | integer | no | Page size: default 20, max 100 (larger values are treated as 100) |
| `page_token` | query | string | no | Page token: the next_page_token from the previous page; omit for the first page. Opaque — pass it back unchanged |

**Response** (200, `DepositPage`)

| Field | Type | Description |
|---|---|---|
| `deposits` | object (Deposit)\[] |  |
| `deposits[].amount` | string | Amount (main unit) |
| `deposits[].amount_raw` | string | Amount (integer, smallest unit) |
| `deposits[].block_number` | string |  |
| `deposits[].chain_code` | string |  |
| `deposits[].confirm_time` | string | Confirmation / credit time (Unix milliseconds); 0 if not confirmed |
| `deposits[].confirmations` | integer |  |
| `deposits[].create_time` | string | Detection time (Unix milliseconds) |
| `deposits[].decimals` | integer |  |
| `deposits[].deposit_id` | string |  |
| `deposits[].from_address` | string | Sender address; for internal transfers, the platform's outbound hot wallet address |
| `deposits[].internal` | boolean | Whether it is an internal transfer (the sender is another user on the platform; not on-chain, credited instantly) |
| `deposits[].log_index` | integer | Log index within the transaction (distinguishes multiple transfers in one transaction) |
| `deposits[].status` | string | PENDING (confirming, not credited) / CONFIRMED (credited) / FAILED / REORGED / BELOW_MIN (below the minimum deposit; recorded but not credited) |
| `deposits[].to_address` | string |  |
| `deposits[].token_code` | string |  |
| `deposits[].tx_hash` | string | On-chain transaction hash; empty for internal transfers |
| `deposits[].user_id` | string |  |
| `next_page_token` | string | page_token for the next page; empty means no more pages |

Response example:

```json
{
  "deposits": [
    {
      "amount": "12.5",
      "amount_raw": "12500000",
      "block_number": "77123456",
      "chain_code": "TRON",
      "confirm_time": "1762650000000",
      "confirmations": 0,
      "create_time": "1762650000000",
      "decimals": 6,
      "deposit_id": "1987654321098752",
      "from_address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "internal": false,
      "log_index": 0,
      "status": "PENDING",
      "to_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
      "token_code": "USDT",
      "tx_hash": "3f1c0e…（交易哈希）",
      "user_id": "u_10001"
    }
  ],
  "next_page_token": ""
}
```

On failure the unified error body is returned; see [Errors](/en/guide/errors).

## Get deposit

```http
GET /v1/deposits/{deposit_id}
```

API key scope: `read`

Get deposit

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `deposit_id` | path | string | yes | Deposit ID |

**Response** (200, `Deposit`)

| Field | Type | Description |
|---|---|---|
| `amount` | string | Amount (main unit) |
| `amount_raw` | string | Amount (integer, smallest unit) |
| `block_number` | string |  |
| `chain_code` | string |  |
| `confirm_time` | string | Confirmation / credit time (Unix milliseconds); 0 if not confirmed |
| `confirmations` | integer |  |
| `create_time` | string | Detection time (Unix milliseconds) |
| `decimals` | integer |  |
| `deposit_id` | string |  |
| `from_address` | string | Sender address; for internal transfers, the platform's outbound hot wallet address |
| `internal` | boolean | Whether it is an internal transfer (the sender is another user on the platform; not on-chain, credited instantly) |
| `log_index` | integer | Log index within the transaction (distinguishes multiple transfers in one transaction) |
| `status` | string | PENDING (confirming, not credited) / CONFIRMED (credited) / FAILED / REORGED / BELOW_MIN (below the minimum deposit; recorded but not credited) |
| `to_address` | string |  |
| `token_code` | string |  |
| `tx_hash` | string | On-chain transaction hash; empty for internal transfers |
| `user_id` | string |  |

Response example:

```json
{
  "amount": "12.5",
  "amount_raw": "12500000",
  "block_number": "77123456",
  "chain_code": "TRON",
  "confirm_time": "1762650000000",
  "confirmations": 0,
  "create_time": "1762650000000",
  "decimals": 6,
  "deposit_id": "1987654321098752",
  "from_address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "internal": false,
  "log_index": 0,
  "status": "PENDING",
  "to_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "token_code": "USDT",
  "tx_hash": "3f1c0e…（交易哈希）",
  "user_id": "u_10001"
}
```

On failure the unified error body is returned; see [Errors](/en/guide/errors).

## Rescan by transaction hash

```http
POST /v1/deposits/rescan
```

API key scope: `deposit`

Rescan by transaction hash: re-detect deposits to this user in the transaction (use when a deposit was missed); already-detected deposits are never credited twice

**Request body**

| Field | Type | Description |
|---|---|---|
| `chain_code` | string | Chain code |
| `tx_hash` | string | Transaction hash |
| `user_id` | string | User ID: the merchant's own user identifier |

Request example:

```json
{
  "chain_code": "TRON",
  "tx_hash": "3f1c0e…（交易哈希）",
  "user_id": "u_10001"
}
```

**Response** (200, `RescanResult`)

| Field | Type | Description |
|---|---|---|
| `chain_code` | string |  |
| `items` | object (RescanResultItem)\[] |  |
| `items[].amount` | string | Amount (main unit) |
| `items[].deposit_id` | string | Deposit ID; empty if the transfer was skipped (e.g. native coin, unregistered token) |
| `items[].log_index` | integer |  |
| `items[].status` | string | Deposit status; SKIPPED if skipped |
| `items[].to_address` | string |  |
| `message` | string |  |
| `result` | string | ACCEPTED: at least one deposit was recorded and awaits confirmation; SKIPPED: nothing to credit |
| `tx_hash` | string |  |

Response example:

```json
{
  "chain_code": "TRON",
  "items": [
    {
      "amount": "12.5",
      "deposit_id": "1987654321098752",
      "log_index": 0,
      "status": "SKIPPED",
      "to_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"
    }
  ],
  "message": "amount below minimum",
  "result": "",
  "tx_hash": "3f1c0e…（交易哈希）"
}
```

On failure the unified error body is returned; see [Errors](/en/guide/errors).