Process Crypto Deposits

This guide explains how to programmatically facilitate cryptocurrency deposits into your Busha Business crypto balances (e.g., BTC, ETH, USDT). Crypto deposits, like fiat deposits, rely on Quotes to generate specific deposit instructions, but with a focus on crypto wallet addresses and networks.

What You’ll Achieve:

Understand the specific quote requirements for crypto deposits.
Generate a deposit quote that provisions a crypto wallet address.
Finalize the deposit transfer to obtain the unique deposit address.
Learn how to instruct your users on making a crypto transfer.
Monitor the status of crypto deposits.

Prerequisites

Before you begin, ensure you have:

A Busha Business Account and Secret API Key (from the Quick Start Tutorial).
An understanding of API Environments (Sandbox vs. Production) and their base URLs (from the Making Your First Request Guide).
A conceptual understanding of Quotes (from the Understanding Quotes Explainer)
Familiarity with creating basic quotes (from the Creating A Quote Guide).

For deposit requests involving a customer, the X-BU-PROFILE-ID field should be included in the request header, and its value should be set to the customer ID for whom the request is performed on their behalf.

Process Crypto Deposit

Get a Quote for the Crypto Deposit

Crypto deposits are initiated by creating a Quote where both the source_currency and target_currency are the same cryptocurrency (e.g., BTC to BTC, USDT to USDT).The critical distinction from fiat deposits is. the pay_in object, which specifies type: "address" and the corresponding network for the cryptocurrency (e.g., “BTC” for Bitcoin, “ERC20” for Ethereum-based tokens like USDT). This informs Busha to prepare for generating a unique wallet address in that specific network upon transfer finalization.To get a crypto deposit quote:

Open your terminal or command prompt.
Construct a POST request to the /v1/quotes endpoint.
Specify the source_currency and target_currency (both being the crypto you expect to receive), the source_amount the user intends to deposit, and a pay_in object with type: "address" and network.
Replace {address} with the recipient address.
Replace YOUR_BASE_URL with your chosen environment’s URL and YOUR_SECRET_KEY with your actual key.

Create Quote

$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/quotes \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_currency": "BTC",
    "target_currency": "BTC",
    "source_amount": "0.0001",
    "pay_in": {
      "type": "address",
      "network": "BTC",
      "address": {address}
    }
  }'

Expected Quoted Response:A successful response will return a standard Quote object. Note the id of the returned Quote (QUO_nEnsWPZ8KErY598DCj9Pk in the example data provided) , as you will need this ID for the next step. The pay_in object in the quote response will mirror what you sent in the request.

{
  "status": "success",
  "message": "Created quote successfully",
  "data": {
    "id": "QUO_nEnsWPZ8KErY598DCj9Pk",
    "profile_id": "BUS_tg6yujbZ1nMu5BLQkPGGO",
    "source_currency": "BTC",
    "target_currency": "BTC",
    "source_amount": "0.0001",
    "target_amount": "0.0001",
    "rate": {
      "product": "",
      "rate": "1",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "BTC"
    },
    "fees": [],
    "pay_in": {
      "network": "BTC",
      "type": "address"
    },
    "reference": "QUO_nEnsWPZ8KErY598DCj9Pk",
    "status": "pending",
    "created_at": "2025-02-24T14:52:33.221141634Z",
    "updated_at": "2025-02-24T14:52:33.221141634Z"
  }
}

Finalize the Deposit Transfer (Generate Crypto Wallet Address)

After obtaining a valid Quote for a crypto deposit, you finalize the transfer. This crucial step is where Busha actually generates the unique crypto wallet address that your user will send funds to. The transfer object is initiated by using the POST /v1/transfers endpoint.To finalize the deposit transfer:

Use the POST request below to the /v1/transfers endpoint.
Include the quote_id obtained from Step 1.
Replace YOUR_BASE_URL and YOUR_SECRET_KEY with your actual details.

$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/transfers \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "quote_id": "QUO_nEnsWPZ8KErY598DCj9Pk"
  }'

Sample Response with Generated Crypto Wallet AddressA successful response will return a Transfer object. This unique crypto wallet address will be located within the data.pay_in.address object of this response.

{
  "status": "success",
  "message": "Created transfer successfully",
  "data": {
    "id": "TRF_ZALYpZBvgHLLImcWY9CxI",
    "profile_id": "BUS_tg6yujbZ1nMu5BLQkPGGO",
    "quote_id": "QUO_nEnsWPZ8KErY598DCj9Pk",
    "source_currency": "BTC",
    "target_currency": "BTC",
    "source_amount": "0.0001",
    "target_amount": "0.0001",
    "rate": {
      "rate": "1",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "BTC"
    },
    "fees": [],
    "pay_in": {
      "address": "tb1qzw4ynldc55lpkx3vcsk03susv9nwzj6qp78qsq",
      "expires_at": "2025-02-24T15:53:33.518656Z",
      "network": "BTC",
      "type": "address"
    },
    "status": "pending",
    "created_at": "2025-02-24T14:53:32.411488796Z",
    "updated_at": "2025-02-24T14:53:32.411488876Z"
  }
}

Instruct Your User and Monitor Deposit Status

Once you have the crypto wallet address and network details, your application should display these to the end-user, along with clear instructions to make the crypto transfer.

It is critical to instruct users to send the exact amount to the correct address on the specified network.

After the user initiates the transfer, you’ll need to monitor its status to confirm when the funds have been successfully deposited into your Busha balance.To monitor deposit status:

Webhooks (Recommended): Set up a webhook endpoint to receive real-time notifications from Busha when the transfer status changes (e.g., from pending to completed or failed). This is the most efficient method for real-time updates.
Polling (Less Recommended): Periodically GET the transfer status using the transfer id TRF_ZALYpZBvgHLLImcWY9CxI in the example). While it is possible, this is less efficient and can lead to rate limiting if done too frequently.

Troubleshooting Common Fiat Deposit Issues

Deposit received after quote expiry: Quotes are valid for 3 minutes from creation. After that, they expire and transfers can no longer be created from them. Create the transfer before the quote expires. The quoted rate is honoured for the remainder of the same 3-minute quote validity window; creating a transfer does not restart it. For transfers involving deposits, ensure the deposit is received within the same quote validity window. Deposits received outside that window are settled at the market rate.
User sends wrong amount: If the user sends an amount different from the source_amount specified in the quote, the deposit may fail or be delayed. Advise users to send the exact amount.
User sends to wrong address/network: Funds sent to an incorrect address or on the wrong network may be unrecoverable. Emphasize the importance of accuracy.
Deposit not reflecting: Check the transfer status via API/webhooks. If still pending after an extended period, contact Busha support with the TRF_ ID.
Payment instruction validity: Follow any separate validity limits returned for the deposit address or temporary bank account in pay_in. These limits do not define the lifetime of the quote or transfer, or extend the 3-minute quote validity window.

What’s Next?

Now that you know how to process fiat deposits, consider:

Processing Fiat Deposits.
Processing Payouts
Exploring all relevant API endpoints: Quotes API Reference, Transfers API Reference.

Start Here

Accept Payments (API)

Accept Payments (SDK & Widgets)

On/Off Ramp (API)

Customer Onboarding (B2B2C)

Balance & Treasury

Recipients

Token Sharing

Request ID

OAuth2

Pledges

Webhooks

Reference

Prerequisites

Process Crypto Deposit

Get a Quote for the Crypto Deposit

Finalize the Deposit Transfer (Generate Crypto Wallet Address)

Instruct Your User and Monitor Deposit Status

Troubleshooting Common Fiat Deposit Issues

What’s Next?

​Prerequisites

​Process Crypto Deposit

Get a Quote for the Crypto Deposit

Finalize the Deposit Transfer (Generate Crypto Wallet Address)

Instruct Your User and Monitor Deposit Status

​Troubleshooting Common Fiat Deposit Issues

​What’s Next?

Prerequisites

Process Crypto Deposit

Troubleshooting Common Fiat Deposit Issues

What’s Next?