User wallets

User wallets: deposit addresses and balances

All deposit addresses of a user

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:

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

Get or create a deposit address

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:

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

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

On failure the unified error body is returned; see Errors.

User balances

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:

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