Crypto withdrawal via the REST API

This guide walks you through supporting crypto withdrawals using the REST API.

Prerequisites

The user has completed onboarding and has the required capabilities enabled.

If the destination network requires an additional reference (e.g., destination tag, memo), strongly encourage your users to provide it. Missing references often lead to loss of funds or lengthy recovery.

Walkthrough

Check available rails

Call List rails to confirm the asset and network the user wants to withdraw to, and verify the withdraw feature is enabled.

GET /core/rails?type=crypto&asset=BTC

A successful response lists all rails for the asset. Each rail includes a features array — only proceed with networks that include "withdraw". For assets supported by multiple networks, require an explicit network selection from the user. Use the network’s reference field to determine whether to show a destination tag or memo input in your UI.

{
  "rails": [
    {
      "type": "crypto",
      "network": "bitcoin",
      "method": "crypto-transaction",
      "asset": "BTC",
      "decimals": 8,
      "features": [
        "deposit",
        "withdraw"
      ]
    },
    {
      "type": "crypto",
      "network": "lightning",
      "method": "crypto-transaction",
      "asset": "BTC",
      "decimals": 8,
      "features": []
    }
  ]
}

Select source account

Crypto withdrawals can be sourced from any account. If the selected account is not in the withdrawal asset, the balance will be converted at the time of the transaction using Uphold’s prevailing rate. Make sure the origin asset has the necessary features enabled. Call List accounts to retrieve the user’s accounts and let them choose one with sufficient balance for the withdrawal.

GET /core/accounts?currency=BTC

{
  "accounts": [
    {
      "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
      "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
      "label": "My BTC account",
      "asset": "BTC",
      "balance": {
        "total": "0.05",
        "available": "0.05"
      }
    }
  ]
}

Select a destination

Crypto withdrawals support two ways of specifying the destination: a raw crypto-address (address entered on every transaction) or a saved external-account of type crypto (address registered once via Create external account, then reused across withdrawals).

Raw crypto address
Saved crypto external account

Collect the destination asset, network and address from the user on each withdrawal.

Call List external accounts filtering for type: "crypto" to let the user pick a previously registered address.

GET /core/external-accounts?type=crypto

Present the accounts to the user and make sure the selected one has status: "ok" and "withdraw" in features.

{
  "externalAccounts": [
    {
      "id": "d0686449-36c7-c62e-b81f-de844bbc79d4",
      "type": "crypto",
      "status": "ok",
      "label": "My XRP Address",
      "asset": "XRP",
      "network": "xrp-ledger",
      "features": [
        "withdraw"
      ],
      "details": {
        "address": "rN7n7otQDd6FczFgLdlqtyMVrn3WD6CJYy",
        "reference": "67809592"
      }
    }
  ]
}

Create a quote

Create a quote for the withdrawal using the Create quote endpoint.

Raw crypto address
Saved crypto external account

POST /core/transactions/quote
{
  "origin": {
    "type": "account",
    "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8"
  },
  "destination": {
    "type": "crypto-address",
    "asset": "BTC",
    "network": "bitcoin",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  },
  "denomination": {
    "asset": "GBP",
    "amount": "100.00",
    "target": "origin"
  }
}

A successful response returns a quote object with details about the withdrawal, including fees and expiration.

{
  "quote": {
    "id": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
    "origin": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "0.00002629253259492961",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      }
    },
    "destination": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "1",
      "node": {
        "type": "crypto-address",
        "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
        "network": "bitcoin",
        "execution": {
          "mode": "onchain"
        }
      }
    },
    "denomination": {
      "amount": "100.00",
      "asset": "GBP",
      "target": "origin",
      "rate": "0.00001210225938333485"
    },
    "fees": [],
    "expiresAt": "2024-07-24T15:22:39Z"
  }
}

Reference the external account by id instead of providing raw address details.

POST /core/transactions/quote
{
  "origin": {
    "type": "account",
    "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8"
  },
  "destination": {
    "type": "external-account",
    "id": "d0686449-36c7-c62e-b81f-de844bbc79d4"
  },
  "denomination": {
    "asset": "GBP",
    "amount": "100.00",
    "target": "origin"
  }
}

The response’s destination.node identifies the external account used, tagged with via: "crypto".

{
  "quote": {
    "id": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
    "origin": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "0.00002629253259492961",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      }
    },
    "destination": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "1",
      "node": {
        "type": "external-account",
        "via": "crypto",
        "id": "d0686449-36c7-c62e-b81f-de844bbc79d4",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
        "network": "xrp-ledger"
      }
    },
    "denomination": {
      "amount": "100.00",
      "asset": "GBP",
      "target": "origin",
      "rate": "0.00001210225938333485"
    },
    "fees": [],
    "expiresAt": "2024-07-24T15:22:39Z"
  }
}

If the account’s rail doesn’t have the withdraw feature, or the network you request doesn’t match the account’s own network, the quote is rejected with transaction_node_invalid:

{
  "code": "transaction_node_invalid",
  "message": "The destination external account lacks 'withdraw' feature"
}

{
  "code": "transaction_node_invalid",
  "message": "The destination external account does not support the specified network"
}

Quotes typically expire quickly. Prompt for user confirmation within the expiry window and regenerate if needed.

Handle quote requirements

When the quote is returned, check the requirements array. If non-empty, resolve each requirement before creating the transaction.

{
  "quote": {
    "id": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
    "requirements": [
      "travel-rule"
    ],
    "expiresAt": "2024-07-24T15:22:39Z"
  }
}

Travel Rule

If the requirements array contains travel-rule, you must collect the required originator and beneficiary information before creating the transaction. For the full step-by-step implementation, see the Travel Rule withdrawal guide.

Create a transaction

Once the user confirms the quote, create the transaction using the Create transaction endpoint.

POST /core/transactions
{
  "quoteId": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0"
}

In a successful crypto withdrawal, the origin is the source account and the destination is a crypto-address node reflecting the recipient’s on-chain address.

{
  "transaction": {
    "id": "223c24c5-76c6-4553-91bc-5af519441f03",
    "origin": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "0.00002629253259492961",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      }
    },
    "destination": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "1",
      "node": {
        "type": "crypto-address",
        "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
        "network": "bitcoin",
        "execution": {
          "mode": "onchain"
        }
      }
    },
    "fees": [],
    "status": "processing",
    "quotedAt": "2024-07-24T15:02:39Z",
    "createdAt": "2024-07-24T15:22:39Z",
    "updatedAt": "2024-07-24T15:22:39Z",
    "denomination": {
      "amount": "100.00",
      "asset": "GBP",
      "target": "origin",
      "rate": "0.00001210225938333485"
    }
  }
}

Execution modes

Crypto withdrawals are executed in one of the following modes, indicated by destination.node.execution.mode:

On-chain

The transaction is broadcast to the blockchain network. destination.node.execution.mode is onchain, and destination.node.execution.transactionHash is set once the transaction is completed.

Off-chain

When both the sender and recipient are Uphold users, the transfer is processed within Uphold’s infrastructure instead of the blockchain. This avoids network fees and is faster than on-chain processing.Each side sees the transfer from its own perspective:

	Sender	Recipient
Seen as	Withdrawal	Deposit
`origin.node.type`	`account`	`crypto-address`
`destination.node.type`	`crypto-address`	`account`

When both users belong to the same organization, the execution also identifies the counterpart account: destination.node.execution.accountOwnerId and destination.node.execution.accountId for the sender, and origin.node.execution.accountOwnerId and origin.node.execution.accountId for the recipient.Because funds move between Uphold accounts, the assets may differ from an on-chain transfer:

Sender: destination.asset is the asset of the recipient account associated with the address, which may differ from the one in the quote.
Recipient: origin.asset is the asset of the sender’s account, which may differ from the network’s asset or even be one the network doesn’t support, such as a fiat asset.

Simulated

Used in development environments for testing. The transaction appears processed without affecting blockchain state, although user balances are updated. destination.node.execution.mode is simulated.

If the destination was a saved external-account, destination.node keeps the same { type: "external-account", via: "crypto", id, ownerId, network } shape shown in Create a quote above, with an execution object added once on-chain details are known.

Monitor for settlement

Prefer webhooks for real-time updates, or fall back to polling if webhooks are not feasible.

Webhook events (recommended):
- core.transaction.created
  - status: processing → initiated but not yet broadcast
- core.transaction.status-changed
  - status: completed → broadcast and confirmed
  - status: on-hold → transaction checks paused (e.g., pending RFIs)
  - status: failed → transaction failed, check statusDetails for more info
Polling (fallback): Get transaction

Notify the user

Display an in-app confirmation when the transaction is completed, and send an email if applicable.

You now support crypto withdrawals with the Enterprise API Suite.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Crypto withdrawal via the REST API

Prerequisites

Walkthrough

Check available rails

Select source account

Select a destination

Create a quote

Handle quote requirements

Travel Rule

Create a transaction

Execution modes

Monitor for settlement

Notify the user

​Prerequisites

​Walkthrough

​Check available rails

​Select source account

​Select a destination

​Create a quote

​Handle quote requirements

​Travel Rule

​Create a transaction

​Execution modes

​Monitor for settlement

​Notify the user

Prerequisites

Walkthrough

Check available rails

Select source account

Select a destination

Create a quote

Handle quote requirements

Travel Rule

Create a transaction

Execution modes

Monitor for settlement

Notify the user