Withdrawals API Reference

All withdrawal endpoints are mounted at /v1/withdrawals and accept X-API-Key. Settlements are always in USDT; withdrawals are currently manual and USDT-only, processed via the platform's configured exchange. Decimal amounts are returned as JSON strings.

Endpoints summary

Method	Path	Description
GET	/v1/withdrawals/balance	Balance summary (total / reserved / available)
GET	/v1/withdrawals/chains	Chains where USDT withdrawals are supported
GET	/v1/withdrawals/wallets	List configured withdrawal wallets
PUT	/v1/withdrawals/wallets/{chain_id}	Create or update the wallet for a chain
DELETE	/v1/withdrawals/wallets/{chain_id}	Remove a wallet (204)
GET	/v1/withdrawals/fee-estimate	Fee + minimum withdrawal for a chain
POST	/v1/withdrawals/request	Create a withdrawal request (Basic KYC)
GET	/v1/withdrawals	List withdrawals (paginated)
GET	/v1/withdrawals/{withdrawal_id}	Withdrawal detail

GET /v1/withdrawals/balance

Response (200 OK):

{
  "success": true,
  "data": {
    "balance_usd": "147.75",
    "reserved_usd": "0.00",
    "available_usd": "147.75"
  }
}

• balance_usd — ledger credits minus debits
• reserved_usd — amounts locked by withdrawals pending admin approval
• available_usd — amount you can request right now

GET /v1/withdrawals/chains

Returns chains where the active exchange supports USDT withdrawals and USDT is active.

Response (200 OK):

{
  "success": true,
  "data": {
    "chains": [
      { "id": "...", "name": "Ethereum", "short_name": "eth", "chain_type": "evm", "logo_url": "https://..." }
    ]
  }
}

PUT /v1/withdrawals/wallets/

Request body:

Field	Type	Required	Description
address	string	Yes	Destination wallet address on the chain
label	string	No	Optional label

Response (200 OK):

{
  "success": true,
  "data": {
    "id": "...",
    "chain": { "id": "...", "name": "Ethereum", "short_name": "eth", "chain_type": "evm" },
    "address": "0xyourwallet...",
    "label": "Cold wallet",
    "created_at": "2026-05-16T10:00:00Z"
  }
}

There is one wallet per chain — re-PUT to replace the address.

GET /v1/withdrawals/fee-estimate

Query parameter: chain_id (UUID, required).

Response (200 OK):

{
  "success": true,
  "data": {
    "chain": { "id": "...", "name": "Ethereum", "short_name": "eth", "chain_type": "evm" },
    "fee_usd": "1.00",
    "min_withdrawal_usd": "10.00"
  }
}

POST /v1/withdrawals/request

Create a manual withdrawal request. Requires Basic KYC.

Request body:

Field	Type	Required	Description
chain_id	UUID	Yes	Chain to withdraw on (must have a configured wallet)
amount_usd	decimal	Yes	Gross amount; must be ≥ minimum and above the fee
totp_code	string	Only if 2FA enabled	6-digit TOTP code or a backup code

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "w1x2y3z4-...",
    "chain": { "id": "...", "name": "Ethereum", "short_name": "eth", "chain_type": "evm" },
    "destination_address": "0xyourwallet...",
    "amount_usd": "147.75",
    "fee_usd": "1.00",
    "net_amount_usd": "146.75",
    "source": "manual",
    "status": "pending_approval",
    "tx_hash": null,
    "created_at": "2026-05-16T14:00:00Z",
    "updated_at": "2026-05-16T14:00:00Z"
  }
}

Lifecycle: pending_approval → (admin approves) processing → completed, or rejected / failed.

Error codes:

Code	Condition
KYC_REQUIRED	KYC level below Basic
UNAUTHORIZED	2FA enabled but totp_code missing or invalid
VALIDATION_ERROR	No wallet configured; chain not supported for USDT withdrawal; below minimum; net amount ≤ 0 after fee; daily limit (Basic KYC, default $50k/24h) would be exceeded
INSUFFICIENT_FUNDS	Amount exceeds available balance

GET /v1/withdrawals

Query parameters: status (string), page (default 1), page_size (default 20, max 100).

Response (200 OK):

{
  "success": true,
  "data": {
    "total": 12,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "withdrawals": [
      {
        "id": "w1x2y3z4-...",
        "chain": { "id": "...", "name": "Ethereum", "short_name": "eth", "chain_type": "evm" },
        "destination_address": "0xyourwallet...",
        "amount_usd": "147.75",
        "fee_usd": "1.00",
        "net_amount_usd": "146.75",
        "source": "manual",
        "status": "completed",
        "tx_hash": "0xwithdrawal...",
        "created_at": "2026-05-16T14:00:00Z",
        "completed_at": "2026-05-16T15:00:00Z"
      }
    ]
  }
}

GET /v1/withdrawals/

Full withdrawal detail, including rejection_reason / failure_reason and review/processing timestamps. Returns NOT_FOUND if the withdrawal is not yours.