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 Make Your First Request Guide).
A conceptual understanding of Quotes (from the Understanding Quotes Explainer)
Familiarity with creating basic quotes (from the How to Create Your First 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.

Step 1: 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.

$ 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"
  }
}

Step 2: 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 Address

A 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"
  }
}

Step 3: 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

“Quote expired” during transfer finalization: Always create a fresh quote immediately before attempting to finalize the transfer.
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.
Address expires: Ensure the user makes the transfer before the pay_in.expires_at time shown in the transfer response. If expired, you may need to initiate a new deposit flow.

What’s Next?

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

How to Process Fiat Deposits Guide.
How to Make Payouts Guide
Exploring all relevant API endpoints: Quotes API Reference, Transfers API Reference.