Your API writes.
Your dashboard reads.
Create a custody user for each user of your app. They get lifetime deposit addresses, every deposit is credited to their balance, and you follow it all in the dashboard.
One custody user per user of your app
Your application creates custody users with its own user ID (external_id) and keeps the returned id. Each custody user has lifetime deposit addresses and their own balance per coin, inside your gateway. The dashboard lists them, but cannot create them: that is done through the API.
1. Create the user
Send your user ID, and optionally a name, email and metadata. Calling it again with the same external_id returns the same user, so it is safe to repeat.
curl https://coino.live/api/v2/custody/users \
-H "Authorization: Bearer ck_live_..." \
-H "Content-Type: application/json" \
-d '{"external_id": "customer_1001", "name": "Sara", "email": "[email protected]"}'2. Show the user their deposit addresses
The answer lists the user's addresses, which coins and networks each one accepts, and their balances. Addresses never change, so your app can show them permanently, for example on a "Deposit" page.
{"data": {
"id": "01m6…", "external_id": "customer_1001", "status": "active",
"addresses": [{"address": "TQ5x…", "networks": ["tron"], "assets": ["usdt-tron", "trx-tron"]}, …],
"balances": [{"asset": "usdt-tron", "balance": "125.5"}]
}}3. Deposits are credited automatically
When a user sends coins to one of their addresses, we send the webhook custody.deposit.detected, and custody.deposit.credited once it is confirmed and added to their balance. You can also list credited deposits at any time, newest first.
Credit your user in your own app on custody.deposit.credited, and use the deposit id to never credit the same deposit twice.
4. Move balances to your main balance
A custody user's balance belongs to that user in your gateway. Move it to your main balance by API (all of it, or an amount), with the button on the user's page in the dashboard, or automatically for every credited deposit with the setting in the gateway. Withdrawals are paid from your main balance.
Status handling
| Dashboard state | Meaning | Available balance |
|---|---|---|
| Confirming | The deposit was seen on the blockchain and is waiting for confirmations. | Unchanged |
| Credited | The deposit is confirmed and added to the user's balance (minus fees). | Increased by the credited amount |
| Held for review | Our team checks the deposit before it is credited. | Unchanged |
A deposit is credited exactly once, even if a webhook is delivered twice.
Explore the Custody service