Overview

Wallet addresses are stored per user and can be reused across multiple orders. Each address is associated with a specific coin and network combination. Users can set a default address that will be used automatically when no address is specified in the order.

How it works at PayZu

When a user registers a wallet address, the system validates the address format for the specified network. Once registered, the address can be referenced by ID when creating orders, eliminating the need to input the full address each time.

The wallet management endpoints allow you to:

Register new wallet addresses with validation
List all registered addresses with optional filters
Update address labels for easy identification
Set a default address per coin/network
Remove addresses no longer in use

Address Registration Flow

 _______________________________________________
|  User provides wallet address                 |
|  (coin, network, address, label)              |
|_______________________________________________|
                      |
                      ▼
 _______________________________________________
|  System validates address format              |
|  Checks coin/network compatibility            |
|_______________________________________________|
                      |
                      ▼
 _______________________________________________
|  Address registered                           |
|  Returns wallet address ID                    |
|_______________________________________________|
                      |
                      ▼
 _______________________________________________
|  Address available for orders                 |
|  Can be set as default                        |
|_______________________________________________|

Wallet Address Object

Field	Type	Description
`id`	string	Unique wallet address ID (UUID)
`coin`	string	Cryptocurrency (e.g., `USDT`, `BTC`)
`network`	string	Blockchain network (e.g., `TRX`, `ETH`)
`address`	string	The wallet address
`label`	string	User-defined label for identification
`isDefault`	boolean	Whether this is the default address for this coin/network
`createdAt`	datetime	When the address was registered

Example: Register a Wallet Address

POST /v1/users/wallet-addresses
{
  "coin": "USDT",
  "network": "TRX",
  "address": "TXyz1234567890abcdef",
  "label": "My Main Wallet",
  "isDefault": true
}

Response:

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "coin": "USDT",
  "network": "TRX",
  "address": "TXyz1234567890abcdef",
  "label": "My Main Wallet",
  "isDefault": true,
  "createdAt": "2026-02-13T13:00:00Z"
}

Using Registered Addresses in Orders

When creating an order, you can reference a registered wallet address instead of providing the full address:

POST /v1/orders
{
  "quoteId": "550e8400-e29b-41d4-a716-446655440000",
  "destination": {
    "asset": "USDT",
    "network": "TRX",
    "walletAddressId": "770e8400-e29b-41d4-a716-446655440002"
  }
}

Alternatively, if a default address is set for the coin/network combination, you can omit the address entirely:

POST /v1/orders
{
  "quoteId": "550e8400-e29b-41d4-a716-446655440000",
  "destination": {
    "asset": "USDT",
    "network": "TRX"
  }
}

Best Practices

Validate addresses before registering: Ensure the address is valid for the specified network
Use descriptive labels: Help users identify their wallets (e.g., "Binance", "Ledger Cold Storage")
Set default addresses: Simplifies order creation for frequent transactions
Keep addresses updated: Remove unused addresses to maintain a clean list
Verify network compatibility: USDT on TRX is different from USDT on ETH — ensure correct network selection

Address Format by Network

Network	Address Format	Example
`TRX`	Base58, starts with T	`TXyz1234567890abcdef...`
`ETH`	Hex, starts with 0x	`0x1234567890abcdef...`
`BSC`	Hex, starts with 0x	`0x1234567890abcdef...`
`ARBITRUM`	Hex, starts with 0x	`0x1234567890abcdef...`
`OPTIMISM`	Hex, starts with 0x	`0x1234567890abcdef...`
`MATIC`	Hex, starts with 0x	`0x1234567890abcdef...`
`SOL`	Base58	`ABC123xyz...`
`BTC`	Bech32 (bc1) or Legacy	`bc1qxy2kgdygjrsqtzq2n0yrf...`
`XRP`	Base58, starts with r	`rXyz1234567890...`

Warning: Sending crypto to the wrong network results in permanent loss of funds. Always verify the network matches the destination wallet.