Crypto Wallet
Create a Crypto Withdrawal
Withdraw crypto from a merchant’s VelaFi custody wallet to an address on your withdrawal whitelist.
POST
/
v2
/
assets
/
withdraw
Create a Crypto Withdrawal
curl --request POST \
--url https://api-test.velafi.com/v2/assets/withdraw \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": 123,
"clientId": "<string>",
"crypto": "<string>",
"chainType": "<string>",
"address": "<string>",
"addressTag": "<string>",
"cryptoAmount": 123,
"remark": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/assets/withdraw"
payload = {
"merchantId": 123,
"clientId": "<string>",
"crypto": "<string>",
"chainType": "<string>",
"address": "<string>",
"addressTag": "<string>",
"cryptoAmount": 123,
"remark": "<string>"
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchantId: 123,
clientId: '<string>',
crypto: '<string>',
chainType: '<string>',
address: '<string>',
addressTag: '<string>',
cryptoAmount: 123,
remark: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/assets/withdraw', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/assets/withdraw")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": 123,\n \"clientId\": \"<string>\",\n \"crypto\": \"<string>\",\n \"chainType\": \"<string>\",\n \"address\": \"<string>\",\n \"addressTag\": \"<string>\",\n \"cryptoAmount\": 123,\n \"remark\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"orderId": 123
}
}Use this endpoint to send crypto from a merchant’s VelaFi wallet to another address. The destination must already be on your withdrawal address whitelist. Before you call it, use Get Withdrawal Quota to find the valid
The
chainType values and the minimum amount.
All requests must include the
X-BH-TOKEN header with a business token from GET /v2/token/generate, and Content-Type: application/json.Endpoint
POST https://api.velafi.com/v2/assets/withdraw
Request Parameters
number
required
ID of the merchant whose wallet is debited.
string
required
Your unique identifier for this withdrawal. Reusing a
clientId from an earlier withdrawal of the same kind (external or VelaFi destination) for this merchant is rejected with Duplicate withdrawal request.string
required
Token symbol, for example
USDT.string
required
Network name, for example
TRC20. Use a chainType returned by Get Withdrawal Quota. It must match the chainType of the whitelist entry for this address. A missing or non-matching value makes the request fail.string
required
Destination address. It must be on your whitelist.
string
Memo or tag, for networks that use one. It must match the
addressTag of the whitelist entry.number
required
Amount to withdraw. It must be greater than
0. For external addresses, see the amount rules under Validation and Behavior.string
Free-text note stored with the withdrawal.
Response Fields
number
200 indicates success.string
SUCCESS on success.object
Show data fields
Show data fields
number
ID of the withdrawal record.
needBrokerAudit and refuseReason fields in data are not populated by this endpoint.Example
cURL
curl -X POST https://api.velafi.com/v2/assets/withdraw \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"merchantId": 151209,
"clientId": "withdraw-0001",
"crypto": "USDT",
"chainType": "TRC20",
"address": "YOUR_WHITELISTED_ADDRESS",
"cryptoAmount": 100,
"remark": "supplier payout"
}'
Validation and Behavior
The request is rejected unless your whitelist has an active entry that matches the
address, chainType and addressTag and covers this crypto. Whitelist entries belong to your API user, so they apply to every merchant under it. Account-level controls, such as a withdrawal freeze, can also reject a request to a whitelisted address.- Crypto limit. The withdrawal counts toward the merchant’s crypto limit. A request that would exceed the limit is rejected.
- External addresses. These rules apply only when the destination is not a VelaFi wallet address:
- The amount is truncated to the token’s decimal precision.
- The amount must be greater than the network fee. Otherwise the request fails with
The quantity cannot be less than the handling fee. - If the token has a minimum (
minCryptoAmountgreater than0), the amount must be at least that minimum. Otherwise the request fails withOrder amount is too small. - If the token has a maximum single withdrawal amount, a larger amount fails with
The quantity cannot exceed the maximum quantity. - If on-chain withdrawals are disabled on the network (
allowWithdrawisfalsein Get Withdrawal Quota), the request fails withWithdrawals are temporarily unavailable due to system maintenance.
- VelaFi destination addresses. If the destination is a VelaFi wallet address, no on-chain transaction is made. The withdrawal is booked as an internal transfer with a zero network fee. It appears in Crypto Transfer History.
To be notified of the final status, subscribe to Crypto Withdrawal Event. VelaFi sends it when the withdrawal succeeds, fails, or is cancelled. You can also poll Get Crypto Withdrawal History with your
clientId until status is 6 (successful), 7 (failed) or 9 (cancelled). A withdrawal to a VelaFi wallet address appears in Crypto Transfer History instead. Don’t keep the user’s balance locked on your side indefinitely while you wait: reconcile pending withdrawals against Get Crypto Withdrawal History and apply a timeout.⌘I
Create a Crypto Withdrawal
curl --request POST \
--url https://api-test.velafi.com/v2/assets/withdraw \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": 123,
"clientId": "<string>",
"crypto": "<string>",
"chainType": "<string>",
"address": "<string>",
"addressTag": "<string>",
"cryptoAmount": 123,
"remark": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/assets/withdraw"
payload = {
"merchantId": 123,
"clientId": "<string>",
"crypto": "<string>",
"chainType": "<string>",
"address": "<string>",
"addressTag": "<string>",
"cryptoAmount": 123,
"remark": "<string>"
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchantId: 123,
clientId: '<string>',
crypto: '<string>',
chainType: '<string>',
address: '<string>',
addressTag: '<string>',
cryptoAmount: 123,
remark: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/assets/withdraw', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/assets/withdraw")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": 123,\n \"clientId\": \"<string>\",\n \"crypto\": \"<string>\",\n \"chainType\": \"<string>\",\n \"address\": \"<string>\",\n \"addressTag\": \"<string>\",\n \"cryptoAmount\": 123,\n \"remark\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"orderId": 123
}
}