Withdrawals

Withdraw managed wallet funds to the verified login wallet.

Withdrawals go to your verified login wallet only - the wallet that owns your account, resolved server-side. There is no destination parameter: a leaked API key or hijacked session cannot redirect funds. Self-custody withdrawals are not a Superior API concept; with BYOK, your funds never touch the managed wallet.

POST/wallet/withdraw

curl -X POST https://api.superior.trade/wallet/withdraw \
  -H "x-api-key: st_live_..." \
  -H "content-type: application/json" \
  -H "Idempotency-Key: wd_20260730_001" \
  -d '{ "amount_usd": 100.0 }'

{ "amount_usd": 100.0 }

Response - 202

{
  "id": "wd_01j9ab...",
  "status": "queued",
  "amount_usd": 100.0,
  "destination_wallet": "0xVerifiedLoginWallet...",
  "created_at": "2026-07-30T09:20:00Z"
}

Retries are safe and required. Send an Idempotency-Key header for every withdrawal request. Keys are scoped to your account and retained for 24 hours; if a client loses the 202 response and retries with the same key and body, the API returns the original withdrawal instead of creating a second payout. Reusing the same key with a different body returns 409 idempotency_key_conflict.

GET/wallet/withdrawals/:id

Poll a withdrawal until it reaches a terminal state:

{
  "id": "wd_01j9ab...",
  "status": "broadcast",
  "amount_usd": 100.0,
  "asset": "USDC",
  "chain": "arbitrum",
  "destination_wallet": "0xVerifiedLoginWallet...",
  "tx_hash": "0xabc...",
  "created_at": "2026-07-30T09:20:00Z",
  "updated_at": "2026-07-30T09:20:41Z"
}

status: queued -> processing -> broadcast -> confirmed, or failed with an error object.

GET/wallet/withdrawals

List recent withdrawals with limit/cursor:

{
  "withdrawals": [
    { "id": "wd_01j9ab...", "status": "confirmed", "amount_usd": 100.0, "tx_hash": "0xabc..." }
  ],
  "next_cursor": null
}

Errors