---
url: /reference/deposits.md
---
# 充值

充值记录与补单

## 充值记录

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

API key 权限范围: `read`

充值记录：按 deposit_id 倒序，游标分页

**请求参数**

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `user_id` | 查询 | string | 否 | 用户ID：可选 |
| `chain_code` | 查询 | string | 否 | 链代码：可选 |
| `token_code` | 查询 | string | 否 | 币种代码：可选 |
| `status` | 查询 | string | 否 | 状态：可选 |
| `tx_hash` | 查询 | string | 否 | 交易哈希：可选 |
| `start_time` | 查询 | string | 否 | 开始时间：按发现时间，Unix 毫秒，含 |
| `end_time` | 查询 | string | 否 | 结束时间：按发现时间，Unix 毫秒，含 |
| `page_size` | 查询 | integer | 否 | 每页条数：默认 20，最大 100（超过按 100） |
| `page_token` | 查询 | string | 否 | 分页令牌：上一页返回的 next_page_token，第一页不传；不透明，原样回传 |

**响应** (200, `DepositPage`)

| 字段 | 类型 | 说明 |
|---|---|---|
| `deposits` | object (Deposit)\[] |  |
| `deposits[].amount` | string | 金额（主单位） |
| `deposits[].amount_raw` | string | 金额（最小单位整数） |
| `deposits[].block_number` | string |  |
| `deposits[].chain_code` | string |  |
| `deposits[].confirm_time` | string | 确认入账时间（Unix 毫秒），未确认为 0 |
| `deposits[].confirmations` | integer |  |
| `deposits[].create_time` | string | 发现时间（Unix 毫秒） |
| `deposits[].decimals` | integer |  |
| `deposits[].deposit_id` | string |  |
| `deposits[].from_address` | string | 付款地址；内部转账为平台出账热钱包地址 |
| `deposits[].internal` | boolean | 是否平台内部转账（付款方是平台内其它用户，不上链、即时到账） |
| `deposits[].log_index` | integer | 交易内的事件序号（同一交易多笔转账时区分） |
| `deposits[].status` | string | PENDING（确认中，不可入账）/ CONFIRMED（已入账）/ FAILED / REORGED / BELOW_MIN（低于最小充值额，只记录不入账） |
| `deposits[].to_address` | string |  |
| `deposits[].token_code` | string |  |
| `deposits[].tx_hash` | string | 链上交易哈希；内部转账为空 |
| `deposits[].user_id` | string |  |
| `next_page_token` | string | 下一页的 page_token；为空表示没有更多 |

响应示例：

```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": ""
}
```

失败时返回统一错误体，见 [错误处理](/guide/errors)。

## 单笔充值

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

API key 权限范围: `read`

单笔充值

**请求参数**

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `deposit_id` | 路径 | string | 是 | 充值ID |

**响应** (200, `Deposit`)

| 字段 | 类型 | 说明 |
|---|---|---|
| `amount` | string | 金额（主单位） |
| `amount_raw` | string | 金额（最小单位整数） |
| `block_number` | string |  |
| `chain_code` | string |  |
| `confirm_time` | string | 确认入账时间（Unix 毫秒），未确认为 0 |
| `confirmations` | integer |  |
| `create_time` | string | 发现时间（Unix 毫秒） |
| `decimals` | integer |  |
| `deposit_id` | string |  |
| `from_address` | string | 付款地址；内部转账为平台出账热钱包地址 |
| `internal` | boolean | 是否平台内部转账（付款方是平台内其它用户，不上链、即时到账） |
| `log_index` | integer | 交易内的事件序号（同一交易多笔转账时区分） |
| `status` | string | PENDING（确认中，不可入账）/ CONFIRMED（已入账）/ FAILED / REORGED / BELOW_MIN（低于最小充值额，只记录不入账） |
| `to_address` | string |  |
| `token_code` | string |  |
| `tx_hash` | string | 链上交易哈希；内部转账为空 |
| `user_id` | string |  |

响应示例：

```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"
}
```

失败时返回统一错误体，见 [错误处理](/guide/errors)。

## 按交易哈希补单

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

API key 权限范围: `deposit`

按交易哈希补单：重新识别该交易里转给该用户的充值（漏推送时用）；已识别的不会重复入账

**请求体**

| 字段 | 类型 | 说明 |
|---|---|---|
| `chain_code` | string | 链代码 |
| `tx_hash` | string | 交易哈希 |
| `user_id` | string | 用户ID：商户侧用户标识 |

请求示例：

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

**响应** (200, `RescanResult`)

| 字段 | 类型 | 说明 |
|---|---|---|
| `chain_code` | string |  |
| `items` | object (RescanResultItem)\[] |  |
| `items[].amount` | string | 金额（主单位） |
| `items[].deposit_id` | string | 充值ID；为空表示该笔转账被跳过（如原生币、币种未登记） |
| `items[].log_index` | integer |  |
| `items[].status` | string | 充值状态；被跳过为 SKIPPED |
| `items[].to_address` | string |  |
| `message` | string |  |
| `result` | string | ACCEPTED：至少一笔充值已记录、等待确认入账；SKIPPED：没有可入账的充值 |
| `tx_hash` | string |  |

响应示例：

```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…（交易哈希）"
}
```

失败时返回统一错误体，见 [错误处理](/guide/errors)。