Crypto deposit via the REST API

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

Prerequisites

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

Some networks require destination tags/memos (e.g., XRP, XLM). If a reference is returned with the address, you can check its type by calling Get network endpoint. Educate the user on the importance of providing this information when making the deposit, as it is essential for crediting their account correctly.

Walkthrough

Check available rails

Call List rails to confirm the asset and network the user wants to deposit from, and verify the deposit 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 "deposit". For assets supported by multiple networks, require an explicit network selection from the user.

{
  "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 destination account

Crypto deposits can target any account. If the selected account is not in the deposited asset, the amount will be converted at settlement using Uphold’s prevailing rate. Make sure the destination asset has the necessary features enabled.

Find an existing account

Call List accounts to retrieve the user’s accounts and let them pick the one they want to fund.

GET /core/accounts

{
  "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"
      }
    }
  ]
}

Create a new account

If the user has no accounts, create one with Create account before proceeding.

POST /core/accounts
{
  "label": "My BTC account",
  "asset": "BTC"
}

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

Generate deposit method

Call Set up account deposit method with the target account id, asset, and network.

PUT /core/accounts/{accountId}/deposit-method?type=crypto&asset=BTC&network=bitcoin

A successful response includes the address and, if applicable, a reference (e.g., destination tag, memo).

{
  "depositMethod": {
    "type": "crypto",
    "status": "ok",
    "details": {
      "network": "bitcoin",
      "asset": "BTC",
      "address": "tb1qgu0gacn9pqpnvlqclvdwyz4gfgxz8pptfz4emt"
    }
  }
}

The deposit method may initially return status: processing while the address is being prepared. Call Get account deposit method to confirm it is ready (status: ok) before displaying instructions to the user.

Render the address clearly and, if a reference is present, display it prominently and treat it as required input. We suggest also displaying a QR code to reduce input errors.

Monitor for the incoming transfer

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

Webhook events (recommended):
- core.transaction.created
  - status: processing → detected on-chain but not yet confirmed
- core.transaction.status-changed
  - status: completed → necessary confirmations reached
  - status: on-hold → transaction checks paused (e.g., pending RFIs)
  - status: failed → irrecoverable error
Polling (fallback): Get transaction

Sample transaction

In a successful crypto deposit, the origin is represented as a crypto-address node reflecting the sender’s on-chain address. The destination is the account that was set up to receive the deposit.

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

Execution modes

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

On-chain

The transaction is received from the blockchain network. origin.node.execution.mode is onchain, and origin.node.execution.transactionHash holds the transaction hash, as in the example above.

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, see Simulate crypto deposit. The transaction appears processed without affecting blockchain state, although user balances are updated. origin.node.execution.mode is simulated.

Handle on-hold transactions

If the crypto deposit is placed on-hold with reason pending-requests-for-information, resolve the pending RFIs before the deposit can complete. For the full step-by-step implementation, see the Travel Rule deposit flow guide.

Notify the user

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

You now support crypto deposits 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 deposit via the REST API

Prerequisites

Walkthrough

Check available rails

Select destination account

Find an existing account

Create a new account

Generate deposit method

Monitor for the incoming transfer

Sample transaction

Execution modes

Handle on-hold transactions

Notify the user

​Prerequisites

​Walkthrough

​Check available rails

​Select destination account

​Find an existing account

​Create a new account

​Generate deposit method

​Monitor for the incoming transfer

​Sample transaction

​Execution modes

​Handle on-hold transactions

​Notify the user

Prerequisites

Walkthrough

Check available rails

Select destination account

Find an existing account

Create a new account

Generate deposit method

Monitor for the incoming transfer

Sample transaction

Execution modes

Handle on-hold transactions

Notify the user