---
url: /reference/wallets.md
---
# 用户钱包

用户钱包：充值地址、余额

## 用户的全部充值地址

```http
GET /v1/wallets/{user_id}/addresses
```

API key 权限范围: `read`

用户的全部充值地址；用户不存在返回空列表

**请求参数**

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `user_id` | 路径 | string | 是 | 用户ID：商户侧用户标识 |

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

| 字段 | 类型 | 说明 |
|---|---|---|
| `addresses` | object (Address)\[] |  |
| `addresses[].address` | string |  |
| `addresses[].chain_code` | string |  |
| `addresses[].create_time` | string | 创建时间（Unix 毫秒） |
| `addresses[].status` | string | ACTIVE |
| `addresses[].user_id` | string |  |

响应示例：

```json
{
  "addresses": [
    {
      "address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
      "chain_code": "TRON",
      "create_time": "1762650000000",
      "status": "ACTIVE",
      "user_id": "u_10001"
    }
  ]
}
```

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

## 取或建充值地址

```http
POST /v1/wallets/{user_id}/addresses
```

API key 权限范围: `deposit`

取或建充值地址：用户钱包不存在则创建，该链地址不存在则派生；幂等，重复调用返回同一地址

**请求参数**

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `user_id` | 路径 | string | 是 | 用户ID：商户侧用户标识 |

**请求体**

| 字段 | 类型 | 说明 |
|---|---|---|
| `chain_code` | string | 链代码 |
| `master_key_id` | string | 主密钥ID：可选，仅在用户钱包首次创建时生效，不传用商户当前 ACTIVE 主密钥 |
| `user_id` | string | 用户ID：商户侧用户标识 |

请求示例：

```json
{
  "chain_code": "TRON",
  "master_key_id": "",
  "user_id": "u_10001"
}
```

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

| 字段 | 类型 | 说明 |
|---|---|---|
| `address` | string |  |
| `chain_code` | string |  |
| `create_time` | string | 创建时间（Unix 毫秒） |
| `status` | string | ACTIVE |
| `user_id` | string |  |

响应示例：

```json
{
  "address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "chain_code": "TRON",
  "create_time": "1762650000000",
  "status": "ACTIVE",
  "user_id": "u_10001"
}
```

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

## 用户余额

```http
GET /v1/wallets/{user_id}/balances
```

API key 权限范围: `read`

用户余额：按资产列出可用 / 冻结（只含已入账的确认充值与内部转账）；用户不存在返回空列表

**请求参数**

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `user_id` | 路径 | string | 是 | 用户ID：商户侧用户标识 |

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

| 字段 | 类型 | 说明 |
|---|---|---|
| `balances` | object (Balance)\[] |  |
| `balances[].available` | string | 可用（主单位） |
| `balances[].available_raw` | string | 可用（最小单位整数） |
| `balances[].chain_code` | string |  |
| `balances[].decimals` | integer |  |
| `balances[].frozen` | string | 冻结（主单位） |
| `balances[].frozen_raw` | string | 冻结（最小单位整数） |
| `balances[].token_code` | string |  |
| `balances[].update_time` | string | 最后变动时间（Unix 毫秒） |

响应示例：

```json
{
  "balances": [
    {
      "available": "100.5",
      "available_raw": "100500000",
      "chain_code": "TRON",
      "decimals": 6,
      "frozen": "0",
      "frozen_raw": "0",
      "token_code": "USDT",
      "update_time": "1762650000000"
    }
  ]
}
```

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