用户钱包

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

用户的全部充值地址

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

响应示例：

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

失败时返回统一错误体，见 错误处理。

取或建充值地址

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：商户侧用户标识

请求示例：

{
  "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

响应示例：

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

失败时返回统一错误体，见 错误处理。

用户余额

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 毫秒）

响应示例：

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

失败时返回统一错误体，见 错误处理。