POST/v1/withdrawals

Criar um saque

Inicia uma transferência on-chain do saldo interno da conta para um endereço externo. O saldo é debitado atomicamente — se o broadcast ou a confirmação falharem depois, o saldo é integralmente estornado.

Envie sempre uma Idempotency-Key para evitar gasto duplo acidental em retentativas. O corpo da requisição precisa ser JSON (Content-Type: application/json).

Parâmetros

stringRequired

Ativo a sacar. Precisa ser um de ETH, USDT, BTC, TRX. A conta precisa ter saldo no par (asset, chain) correspondente.

stringRequired

Família de chain para o broadcast. Precisa ser uma de ethereum, tron, bitcoin, e compatível com asset.

stringRequired

Valor a sacar, como string decimal com até 8 casas. Se a taxa é descontada do amount ou somada por cima depende de fee_mode.

stringRequired

Endereço destinatário on-chain. 20–120 chars. Validado contra o formato da chain — endereços inválidos são rejeitados de forma síncrona.

enumOptionalDefault: included

included (a taxa de rede é subtraída do amount; o destinatário recebe menos que amount) ou added (a taxa de rede é debitada do saldo além do amount; o destinatário recebe exatamente amount).

stringOptional

Seu identificador para este saque. Máx 255 chars. Devolvido em todo webhook relacionado.

stringOptional

URL de webhook por saque (http(s), máx 2000 chars). Sobrescreve os endpoints da conta para eventos deste saque.

objectOptional

Pares chave/valor livres devolvidos no objeto withdrawal e em todos os webhooks relacionados.

Retorno

Retorna o objeto Withdrawal criado com status: "pending".

Erros

Status	Code	Description
400	`invalid_request_error`	Parâmetro ausente ou inválido, endereço malformado para a chain, ou `asset`/`chain` não suportada.
400	`insufficient_balance`	O saldo disponível é menor que o total necessário (`amount` mais a taxa quando `fee_mode = "added"`).
401	`authentication_error`	Chave de API ausente ou inválida.
409	`idempotency_key_reused`	A mesma `Idempotency-Key` foi usada com um corpo diferente.

Criar um saque

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
}