Billetera cripto
Crear un retiro cripto
Retira cripto de la billetera de custodia de VelaFi de un comercio a una dirección de tu lista blanca de direcciones de retiro.
POST
/
v2
/
assets
/
withdraw
Crear un retiro cripto
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
}
}Usa este endpoint para enviar cripto de la billetera de VelaFi de un comercio a otra dirección. El destino ya debe estar en tu lista blanca de direcciones de retiro. Antes de llamarlo, usa Consultar cuota de retiro para conocer los valores válidos de
Este endpoint no llena los campos
chainType y el monto mínimo.
Todas las solicitudes deben incluir el encabezado
X-BH-TOKEN con un token de negocio de GET /v2/token/generate, y Content-Type: application/json.Endpoint
POST https://api.velafi.com/v2/assets/withdraw
Parámetros de la solicitud
number
requerido
ID del comercio cuya billetera se debita.
string
requerido
Tu identificador único para este retiro. Si reutilizas un
clientId de un retiro anterior del mismo tipo (destino externo o de VelaFi) para este comercio, la solicitud se rechaza con Duplicate withdrawal request.string
requerido
Símbolo del token, por ejemplo
USDT.string
requerido
Nombre de la red, por ejemplo
TRC20. Usa un chainType devuelto por Consultar cuota de retiro. Debe coincidir con el chainType de la entrada de la lista blanca para esta dirección. Si falta o no coincide, la solicitud falla.string
requerido
Dirección de destino. Debe estar en tu lista blanca.
string
Memo o etiqueta, para las redes que lo usan. Debe coincidir con el
addressTag de la entrada de la lista blanca.number
requerido
Monto a retirar. Debe ser mayor que
0. Para direcciones externas, consulta las reglas de monto en Validación y comportamiento.string
Nota de texto libre que se guarda con el retiro.
Campos de la respuesta
number
200 indica éxito.string
SUCCESS en caso de éxito.object
Mostrar campos de data
Mostrar campos de data
number
ID del registro del retiro.
needBrokerAudit y refuseReason de data.Ejemplo
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"
}'
Validación y comportamiento
La solicitud se rechaza a menos que tu lista blanca tenga una entrada activa que coincida con
address, chainType y addressTag y que cubra este crypto. Las entradas de la lista blanca pertenecen a tu usuario de API, así que aplican a todos los comercios bajo él. Los controles a nivel de cuenta, como un congelamiento de retiros, también pueden rechazar una solicitud a una dirección en la lista blanca.- Límite de cripto. El retiro cuenta para el límite de cripto del comercio. Una solicitud que exceda el límite se rechaza.
- Direcciones externas. Estas reglas aplican solo cuando el destino no es una dirección de billetera de VelaFi:
- El monto se trunca a la precisión decimal del token.
- El monto debe ser mayor que la comisión de red. De lo contrario, la solicitud falla con
The quantity cannot be less than the handling fee. - Si el token tiene un mínimo (
minCryptoAmountmayor que0), el monto debe ser al menos ese mínimo. De lo contrario, la solicitud falla conOrder amount is too small. - Si el token tiene un monto máximo por retiro, un monto mayor falla con
The quantity cannot exceed the maximum quantity. - Si los retiros on-chain están deshabilitados en la red (
allowWithdrawesfalseen Consultar cuota de retiro), la solicitud falla conWithdrawals are temporarily unavailable due to system maintenance.
- Direcciones de destino de VelaFi. Si el destino es una dirección de billetera de VelaFi, no se realiza ninguna transacción on-chain. El retiro se registra como una transferencia interna con comisión de red cero. Aparece en Historial de transferencias de cripto.
Para recibir una notificación del estado final, suscríbete a Evento de retiro de cripto. VelaFi lo envía cuando el retiro es exitoso, falla o se cancela. También puedes consultar periódicamente Historial de retiros de cripto con tu
clientId hasta que status sea 6 (exitoso), 7 (fallido) o 9 (cancelado). Un retiro a una dirección de billetera de VelaFi aparece en cambio en Historial de transferencias de cripto. No mantengas bloqueado indefinidamente el saldo del usuario de tu lado mientras esperas: concilia los retiros pendientes contra Historial de retiros de cripto y aplica un tiempo límite.⌘I
Crear un retiro cripto
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
}
}