> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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](https://docs.velafi.com/es/api-reference/crypto-wallet/get-withdrawal-quota.md) para conocer los valores válidos de `chainType` y el monto mínimo.

> [!NOTE]
>
> 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

**merchantId** `number` *required*

ID del comercio cuya billetera se debita.

**clientId** `string` *required*

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`.

**crypto** `string` *required*

Símbolo del token, por ejemplo `USDT`.

**chainType** `string` *required*

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.

**address** `string` *required*

Dirección de destino. Debe estar en tu lista blanca.

**addressTag** `string`

Memo o etiqueta, para las redes que lo usan. Debe coincidir con el `addressTag` de la entrada de la lista blanca.

**cryptoAmount** `number` *required*

Monto a retirar. Debe ser mayor que `0`. Para direcciones externas, consulta las reglas de monto en Validación y comportamiento.

**remark** `string`

Nota de texto libre que se guarda con el retiro.

## Campos de la respuesta

**code** `number`

`200` indica éxito.

**msg** `string`

`SUCCESS` en caso de éxito.

**data** `object`

**campos de data**

**orderId** `number`

ID del registro del retiro.

Este endpoint no llena los campos `needBrokerAudit` y `refuseReason` de `data`.

## Ejemplo

```bash cURL theme={null}
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

> [!WARNING]
>
> 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 (`minCryptoAmount` mayor que `0`), el monto debe ser al menos ese mínimo. De lo contrario, la solicitud falla con `Order 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 (`allowWithdraw` es `false` en Consultar cuota de retiro), la solicitud falla con `Withdrawals 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](https://docs.velafi.com/es/api-reference/merchant/query-crypto-transfers.md).

> [!NOTE]
>
> Para recibir una notificación del estado final, suscríbete a [Evento de retiro de cripto](https://docs.velafi.com/es/api-reference/webhooks/crypto-withdraw-message-push.md). VelaFi lo envía cuando el retiro es exitoso, falla o se cancela. También puedes consultar periódicamente [Historial de retiros de cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md) 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](https://docs.velafi.com/es/api-reference/merchant/query-crypto-transfers.md). 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.


## Related topics

- [Listar retiros cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)
- [Evento de retiro cripto](https://docs.velafi.com/es/api-reference/webhooks/crypto-withdraw-message-push.md)
- [Crear un webhook](https://docs.velafi.com/es/api-reference/webhooks/create-webhook-endpoints.md)
- [Obtener la cuota de retiro](https://docs.velafi.com/es/api-reference/crypto-wallet/get-withdrawal-quota.md)
- [Crear una transferencia cripto](https://docs.velafi.com/es/api-reference/merchant/crypto-transfer.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.