POST/v1/withdrawals

Create a withdrawal

Initiates an on-chain transfer from the account's internal balance to an external address. The balance is debited atomically — if the broadcast or confirmation later fails, the balance is fully refunded.

Always send an Idempotency-Key to prevent accidental double-spends on retry. The request body must be JSON (Content-Type: application/json).

Parameters

stringRequired

Asset to withdraw. Must be one of ETH, USDT, BTC, TRX. Account must hold a balance for the corresponding (asset, chain) pair.

stringRequired

Chain family to broadcast on. Must be one of ethereum, tron, bitcoin, and compatible with asset.

stringRequired

Amount to withdraw, as a decimal string with up to 8 fractional digits. Whether the fee is taken from this amount or added on top depends on fee_mode.

stringRequired

Recipient on-chain address. 20–120 chars. Validated against the chain's format — invalid addresses are rejected synchronously.

enumOptionalDefault: included

Either included (the network fee is subtracted from amount; recipient receives less than amount) or added (the network fee is debited from the balance in addition to amount; recipient receives exactly amount).

stringOptional

Your own identifier for this withdrawal. Max 255 chars. Returned on every related webhook.

stringOptional

Per-withdrawal webhook URL (http(s), max 2000 chars). Overrides the account-level endpoints for events related to this withdrawal.

objectOptional

Free-form key/value pairs echoed back on the withdrawal object and on all related webhook events.

Returns

Returns the created Withdrawal object with status: "pending".

Errors

Status	Code	Description
400	`invalid_request_error`	Parameter missing or invalid, address malformed for the chain, or `asset`/`chain` not supported.
400	`insufficient_balance`	The available balance is below the required total (`amount` plus fee when `fee_mode = "added"`).
401	`authentication_error`	Missing or invalid API key.
409	`idempotency_key_reused`	The same `Idempotency-Key` was used with a different body.

Create a withdrawal

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
}