Aesesdocs

The Withdrawal object

A withdrawal moves value from the account's internal balance to an external on-chain address. The balance is debited atomically at creation; if the on-chain transaction fails, the balance is refunded.

Lifecycle

  1. pending — accepted, balance debited and locked, awaiting hot-wallet signing.
  2. processing — approved and queued for signing (withdrawals that required manual approval).
  3. broadcasted — transaction signed and broadcast to the network. tx_hash is set, but the funds are not settled yet: the transaction can still be dropped or reverted.
  4. completed — the transaction was mined successfully and reached the network's confirmation threshold. This is the only status that means the recipient was paid.
  5. failed — permanent failure. Balance has been refunded.
  6. cancelled — cancelled before broadcast. Balance has been refunded.
Paid means completed

Only treat a withdrawal as paid on completed. A broadcasted withdrawal can still end as failed (with automatic refund) if the network never mines or reverts the transaction.

Attributes

stringOptional

Unique identifier of the form wd_….

stringOptional

Always "withdrawal".

enumOptional

One of pending, processing, broadcasted, completed, failed, cancelled.

stringOptional

Asset being withdrawn.

stringOptional

Network to broadcast on.

stringOptional

Net amount sent on-chain, as a decimal string.

stringOptional

Fee, in the same asset, debited from the account's balance in addition to amount.

string | nullOptional

Net amount after fees, when a fee policy applies.

stringOptional

Recipient address. Validated against the chain's address format at creation time.

string | nullOptional

On-chain hash once broadcast. In rare cases (a transaction dropped by the network and settled by another one) the final hash on completed may differ from the one sent on broadcasted — always use the value from the latest event.

string | nullOptional

Your own reference, as sent at creation.

string | nullOptional

URL that receives this withdrawal's events.

string | nullOptional

Human-readable failure reason. Present when status is failed.

object | nullOptional

Free-form key/value metadata sent at creation.

integerOptional

Unix timestamp of creation.

Endpoints

withdrawal.created, withdrawal.processing, withdrawal.broadcasted, withdrawal.completed, withdrawal.failed, withdrawal.cancelled.

The Withdrawal object
{
"object": "withdrawal",
"id": "wd_3f2a9c1e7b8d4a6f9e0c1b2a3d4e5f60",
"status": "completed",
"asset": "USDT",
"chain": "ethereum",
"amount": "150.00000000",
"fee": "1.25000000",
"net_amount": null,
"address": "0xRecipientAddress0123456789abcdef01234567",
"tx_hash": "0xabc123...",
"reference_id": "po_8821",
"webhook_url": "https://example.com/webhooks/aeses",
"metadata": { "payout_id": "po_8821" },
"fail_reason": null,
"created_at": 1731600300
}