On-Chain Crypto Withdrawals

Overview

Withdraw crypto from a customer's trading account to an external wallet using a crypto_transfer quote followed by a crypto transfer. The flow mirrors fiat funding but uses different parameters and accounts for on-chain network fees.

Prerequisites

• A customer with a verified identity
• A trading account holding the crypto asset to withdraw
• A registered external wallet for the destination address (see Add External Wallets)

Step 1: Create a crypto transfer quote

Create a quote of type crypto_transfer with side set to withdrawal. This example withdraws 0.25 ETH:

{
  "product_type": "crypto_transfer",
  "customer_guid": "customer_guid",
  "asset": "ETH",
  "side": "withdrawal",
  "deliver_amount": 250000000000000000
}

ℹ️

Base unit precision

The deliver_amount is in base currency units. For ETH, the base unit is wei (18 decimals). The above amount represents 0.25 ETH. This precision is required to avoid rounding errors.

ℹ️

deliver_amount vs receive_amount

deliver_amount fixes what you send; fees come out of what the recipient gets. receive_amount fixes what the recipient gets; you pay fees on top. See Create and execute a trade for the canonical explanation.

For crypto withdrawals, understand the related on-chain gas fees that may accompany the withdrawal. The POST /api/quotes response includes two fields related to network fees:

{
  ...,
  "network_fee": 2900000000000000,
  "network_fee_asset": "ETH"
}

The network_fee shown above is also in the base units of the currency. The above amount represents 0.0029 ETH. Network fees are tracked as a partner liability in the bank's gas account. To clear the liability, transfer from your fee account to the gas account before withdrawing fees — see Platform accounts for the full flow.

Step 2: Execute the transfer

Execute the transfer using POST /api/transfers with the quote GUID from Step 1. Set transfer_type to "crypto" and provide the destination wallet in external_wallet_guid.

{
  "quote_guid": "quote_guid",
  "transfer_type": "crypto",
  "external_wallet_guid": "external_wallet_guid",
  "source_participants": [
    {
      "type": "customer",
      "amount": 250000000000000000,
      "guid": "customer_guid"
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "amount": 250000000000000000,
      "guid": "customer_guid"
    }
  ]
}

The valid type enum values for source_participants and destination_participants are bank, customer, and counterparty. Values such as trading, account, external_wallet, or external_wallet_account are not valid and will result in validation errors.

Key points for crypto withdrawals:

• The guid in each participant must match the chosen type (e.g., the customer GUID for customer).
• The amount field is required in both participant objects and must match the quote amount in base units.
• The external_wallet_guid is set at the top level alongside the participants array; these are not mutually exclusive.

Step 3: Monitor the transfer

Crypto transfers process faster than fiat transfers, typically completing in a few minutes. Poll GET /api/transfers/{transfer_guid} to monitor the transfer state until it reaches completed, or register for webhooks. See Transfer Process for the full state lifecycle.

Once completed, verify the on-chain transaction using a blockchain explorer such as etherscan.io for Ethereum-based assets.

Network fee too low

Encountering the error code network_fee_too_low during a crypto transfer indicates that the base network fee was not met when the transaction was submitted to the blockchain. This may occur due to network volatility between the submission and the authorization/approval of the transfer. Retrying the transfer usually resolves this issue.

Ethereum address format requirements

When withdrawing USDC or other assets to an external wallet on the Ethereum network, ensure the destination address meets the following requirements:

• Starts with 0x
• Is exactly 42 characters long
• Contains only hexadecimal characters (0-9, a-f, A-F)

Addresses that do not meet these criteria may result in failed transfers. Double-check that you are using an Ethereum-compatible address and not one from a different blockchain.

Minimum receive amounts for crypto transfer withdrawals

For crypto_transfer withdrawal quotes, each asset and network may have a specific minimum receive_amount enforced by the platform. For example, USDC_NPL on Polygon enforces a minimum of 1,000,000 base units (1.00 USDC) in production. A quote below the minimum returns a 422 Invalid Quote Amount error. Enforce per-asset minimums in your application before submitting withdrawal quotes.

Sandbox behavior

For sandbox-specific behavior of crypto withdrawals (mocked on-chain confirmations, devnet addresses, Solana rent handling), see Sandbox Transfers.