Version: v0.9

Deposit Addresses

POST

/custody/accounts/:accountId/addresses/:blockchain

Creates or retrieves a deposit address for the specified blockchain on a custody account. If an address already exists for the specified blockchain, the existing address will be returned instead of creating a new one.

Path Parameters

Parameter	Type	Description
accountId required	string	The unique identifier of the custody account
blockchain required	string	The blockchain network to create or retrieve an address for (ETH, BSC, TRX, SOL)

Example Request

POST /custody/accounts/550e8400-e29b-41d4-a716-446655440000/addresses/ETH
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response Parameters

Parameter	Type	Description
account_id	string	The ID of the custody account
blockchain	string	The blockchain network (ETH, BSC, TRX, SOL)
address	string	The deposit address for the specified blockchain
is_new	boolean	Indicates whether the address was newly created (true) or already existed (false)
created_at	string	ISO 8601 timestamp of when the address was first created
qr_code	string	Data URL for a QR code representing the address (can be used in an img tag)

Example Response

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "blockchain": "ETH",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "is_new": false,
  "created_at": "2025-04-15T13:30:25.123Z",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
}

Error Codes

Status Code	Error Code	Description
400	unsupported_blockchain	The specified blockchain is not supported
401	authentication_failed	Authentication failed. Check your API key or JWT token
403	insufficient_permissions	You do not have permission to create addresses for this account
404	account_not_found	Custody account with the specified ID was not found
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint
500	custody_provider_error	An error occurred when creating the address with the custody provider

Notes

The same deposit address will be returned for repeated requests for the same blockchain on the same account
The address can be used for receiving USDT or other supported tokens on the specified blockchain
Always verify the blockchain network before sharing the address with customers to prevent potential loss of funds
The QR code in the response can be displayed to users for easier address scanning

GET

/custody/accounts/:accountId/addresses

Returns all deposit addresses associated with a custody account across all blockchains.

Path Parameters

Parameter	Type	Description
accountId required	string	The unique identifier of the custody account

Example Request

GET /custody/accounts/550e8400-e29b-41d4-a716-446655440000/addresses
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response

[
  {
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "blockchain": "ETH",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "created_at": "2025-04-15T13:30:25.123Z",
    "last_deposit_at": "2025-04-16T10:15:30.456Z",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
  },
  {
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "blockchain": "BSC",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "created_at": "2025-04-15T13:45:10.789Z",
    "last_deposit_at": null,
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
  },
  {
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "blockchain": "TRX",
    "address": "TNVoLnCJbFBphKfXf2YoU8VZhG7eQ7y3o5",
    "created_at": "2025-04-15T14:20:45.123Z",
    "last_deposit_at": null,
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
  }
]

Error Codes

Status Code	Error Code	Description
401	authentication_failed	Authentication failed. Check your API key or JWT token
403	insufficient_permissions	You do not have permission to view addresses for this account
404	account_not_found	Custody account with the specified ID was not found
429	rate_limit_exceeded	You have exceeded the rate limit for this endpoint

Notes

Only blockchains for which addresses have been created will be returned
The last_deposit_at field will be null if no deposits have been received at the address
For some blockchains (like ETH and BSC), the address format may be identical, but they should be treated as separate networks