Skip to main content
This flow covers initiating a crypto withdrawal and monitoring until settlement.

​
Prerequisites

  • The user is onboarded and verified (KYC).
  • A funded account to support the withdrawal.
  • The details of the destination wallet: blockchain address and destination tag/memo if applicable (e.g., XRP/XLM).
  • Your system is set up to listen to webhooks for incoming transactions.
If the destination network requires an additional reference (e.g., destination tag, memo), treat it as mandatory. Missing references often lead to loss or lengthy recovery.

​
The flow

​
Choose a funded account

List the user’s accounts using List Accounts endpoint and let them choose one with sufficient balance for the withdrawal. 
GET /core/accounts?perPage=10&currency=XRP

​
Create a quote

Create a quote for the withdrawal using Create Quote endpoint. 
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"
  }
}

​
Quote object

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"
  }
}
Quotes typically expire quickly. Prompt for user confirmation within the expiry window and regenerate if needed.

​
Create a transaction

Once the user confirms the quote, create the transaction using Create Transaction endpoint. 
POST /core/transactions
{
  "quoteId": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0"
}

​
Transaction object

A successful response returns a transaction object with details about the initiated withdrawal. 
{
  "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 support different execution modes depending on the destination and environment:
  • On-chain execution: The transaction is processed directly on the blockchain network. The destination.node.execution.mode will be "onchain" and include blockchain-specific details such as transaction hashes upon completion.
  • Off-chain execution: When both the sender and recipient are Uphold users, the transaction is processed internally within Uphold’s infrastructure. This eliminates network fees and is faster than onchain processing. The destination.node.execution.mode will be "offchain". For offchain transactions, the execution object includes additional properties: accountOwnerId (the recipient user ID) and accountId (the recipient account ID).
  • Simulated execution: Used in development environments for testing purposes. The transaction appears processed but does not affect actual blockchain state (user balances will be affected though). The destination.node.execution.mode will be "simulated".

​
Monitor for settlement

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

​
Notify the user

Show an in-app confirmation and send an email once the withdrawal is completed.
Congratulations! You’ve successfully implemented the crypto withdrawal flow using the Enterprise API Suite.
⌘I