POST/v1/withdrawals

Crear un retiro

Inicia una transferencia on-chain desde el saldo interno de la cuenta hacia una dirección externa. El saldo se debita de forma atómica — si el broadcast o la confirmación fallan después, el saldo se reembolsa por completo.

Envía siempre una Idempotency-Key para evitar gastos dobles accidentales en reintentos. El cuerpo de la solicitud debe ser JSON (Content-Type: application/json).

Parámetros

stringRequired

Activo a retirar. Debe ser uno de ETH, USDT, BTC, TRX. La cuenta debe tener saldo en el par (asset, chain) correspondiente.

stringRequired

Familia de chain para el broadcast. Debe ser una de ethereum, tron, bitcoin, y compatible con asset.

stringRequired

Monto a retirar, como string decimal con hasta 8 decimales. Si la comisión se descuenta del amount o se suma encima depende de fee_mode.

stringRequired

Dirección destinataria on-chain. 20–120 chars. Validada contra el formato de la chain — direcciones inválidas se rechazan de forma síncrona.

enumOptionalDefault: included

included (la comisión de red se resta del amount; el destinatario recibe menos que amount) o added (la comisión se debita del saldo además del amount; el destinatario recibe exactamente amount).

stringOptional

Tu identificador para este retiro. Máx 255 chars. Devuelto en cada webhook relacionado.

stringOptional

URL de webhook por retiro (http(s), máx 2000 chars). Sobrescribe los endpoints de la cuenta para eventos de este retiro.

objectOptional

Pares clave/valor libres devueltos en el objeto withdrawal y en todos los webhooks relacionados.

Devuelve

Devuelve el objeto Withdrawal creado con status: "pending".

Errores

Status	Code	Description
400	`invalid_request_error`	Parámetro ausente o inválido, dirección mal formada para la chain, o `asset`/`chain` no soportada.
400	`insufficient_balance`	El saldo disponible es menor que el total requerido (`amount` más la comisión cuando `fee_mode = "added"`).
401	`authentication_error`	Clave API ausente o inválida.
409	`idempotency_key_reused`	La misma `Idempotency-Key` se usó con un cuerpo distinto.

Crear un retiro

curl https://api.aeses.io/v1/withdrawals \
-H "x-api-key: sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
  "asset": "USDT",
  "chain": "ethereum",
  "amount": "150.00",
  "address": "0xRecipientAddress0123456789abcdef01234567",
  "fee_mode": "added",
  "reference_id": "payout_8821"
}'

Response

{
"object": "withdrawal",
"id": "wd_01hxyz8n3r6t5vh4k9bmcse2gp",
"status": "pending",
"asset": "USDT",
"chain": "ethereum",
"amount": "150.00000000",
"fee": "1.25000000",
"net_amount": "150.00000000",
"address": "0xRecipientAddress0123456789abcdef01234567",
"tx_hash": null,
"reference_id": "payout_8821",
"webhook_url": null,
"metadata": null,
"fail_reason": null,
"created_at": 1731600300
}