Skip to main content
This flow covers generating a deposit address, monitoring the chain or webhooks, and crediting the user’s account.

​
Prerequisites

  • The user is onboarded and verified (KYC).
  • The user capabilities allow crypto deposits.
  • An account created for the user to receive the deposit.
  • The asset and network are enabled in your environment (e.g., BTC mainnet, ETH mainnet/testnet).
  • Your system is set up to listen to webhooks for incoming transactions.
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. Ensure your user provides this information when making the deposit, as it is essential for crediting their account correctly.

​
The flow

​
Choose asset & network

Confirm the asset (e.g., XRP) and network (e.g., xrp-ledger) that the user wants to deposit.
For assets with multiple networks (e.g., ETH on Ethereum, Starknet, etc.), require an explicit selection.

​
Generate deposit address

Request a deposit address for the user’s account by calling the Set up Account Deposit Method endpoint, specifying the following parameters:
  • type: crypto
  • asset: the asset the user will deposit (e.g., XRP)
  • network: the network the user will deposit from (e.g., xrp-ledger)
POST /core/accounts/{accountId}/deposit-method?type=crypto&asset=XRP&network=xrp-ledger
A successful response includes the address and, if applicable, a reference (e.g., destination tag, memo). 
{
  "depositMethod": {
    "type": "crypto",
    "status": "ok",
    "details": {
      "network": "xrp-ledger",
      "asset": "XRP",
      "address": "rfBtmHiLwwWH5maH2PT78GxubrSydRF9aY",
      "reference": "3457810109"
    }
  }
}

​
Display deposit instructions

Render the address clearly. If a reference is present, display it prominently and treat it as required input. We suggest also displaying a QR code to make it easier for users and reduce possible errors.
It’s important to educate the user about the importance of including the reference, as it is essential for crediting their account correctly.

​
Monitor for incoming transactions

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):

​
Handle on-hold transactions

If the crypto deposit is placed on-hold with reason pending-requests-for-information on arrival, you’ll need to resolve pending RFIs before the deposit can complete. Follow the Transaction RFIs flow to handle this scenario.

​
Transaction object

Below is a sample transaction object returned by the Get Transaction endpoint. The origin field shows how the source of the deposit is represented: 
{
  "transaction": {
    "id": "223c24c5-76c6-4553-91bc-5af519441f03",
    "origin": {
      "asset": "XRP",
      "amount": "1.00",
      "rate": "1.00",
      "node": {
        "type": "crypto-address",
        "network": "xrp-ledger",
        "execution": {
          "mode": "onchain",
          "transactionHash": "C74C5537AB6F766E9A95BCDA536FF239A6956E6BDF30A3357FA3EE174F7FFAB3"
        }
      }
    },
    "destination": {
      "asset": "XRP",
      "amount": "1.00 ",
      "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": "XRP",
      "amount": "1.00",
      "rate": "1.00",
      "target": "origin"
    }
  }
}

​
Execution modes

Crypto deposits are processed using different execution modes depending on the environment and configuration:
  • On-chain execution: The transaction is processed directly on the blockchain network. The origin.node.execution.mode will be "onchain" and include a transactionHash as shown in the example above.
  • 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 origin.node.execution.mode will be "simulated" (Available soon).

​
Notify the user

Keep your users updated on the status of their deposit by using in-app notifications and status emails.
Congratulations! You’ve successfully implemented the crypto deposit flow using the Enterprise API Suite.