---
url: /en/reference/wallets.md
---
# User wallets

User wallets: deposit addresses and balances

## All deposit addresses of a user

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

API key scope: `read`

All deposit addresses of a user; an empty list if the user does not exist

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `user_id` | path | string | yes | User ID: the merchant's own user identifier |

**Response** (200, `AddressList`)

| Field | Type | Description |
|---|---|---|
| `addresses` | object (Address)\[] |  |
| `addresses[].address` | string |  |
| `addresses[].chain_code` | string |  |
| `addresses[].create_time` | string | Creation time (Unix milliseconds) |
| `addresses[].status` | string | ACTIVE |
| `addresses[].user_id` | string |  |

Response example:

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

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

## Get or create a deposit address

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

API key scope: `deposit`

Get or create a deposit address: creates the user wallet if missing and derives the address for the chain if missing; idempotent — repeated calls return the same address

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `user_id` | path | string | yes | User ID: the merchant's own user identifier |

**Request body**

| Field | Type | Description |
|---|---|---|
| `chain_code` | string | Chain code |
| `master_key_id` | string | Master key ID: optional; only takes effect when the user wallet is first created; defaults to the merchant's current ACTIVE master key |
| `user_id` | string | User ID: the merchant's own user identifier |

Request example:

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

**Response** (200, `Address`)

| Field | Type | Description |
|---|---|---|
| `address` | string |  |
| `chain_code` | string |  |
| `create_time` | string | Creation time (Unix milliseconds) |
| `status` | string | ACTIVE |
| `user_id` | string |  |

Response example:

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

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

## User balances

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

API key scope: `read`

User balances: available / frozen per asset (only credited, confirmed deposits and internal transfers); an empty list if the user does not exist

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `user_id` | path | string | yes | User ID: the merchant's own user identifier |

**Response** (200, `BalanceList`)

| Field | Type | Description |
|---|---|---|
| `balances` | object (Balance)\[] |  |
| `balances[].available` | string | Available (main unit) |
| `balances[].available_raw` | string | Available (integer, smallest unit) |
| `balances[].chain_code` | string |  |
| `balances[].decimals` | integer |  |
| `balances[].frozen` | string | Frozen (main unit) |
| `balances[].frozen_raw` | string | Frozen (integer, smallest unit) |
| `balances[].token_code` | string |  |
| `balances[].update_time` | string | Last change time (Unix milliseconds) |

Response example:

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

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