Process Crypto Deposits

This guide explains how to programmatically facilitate cryptocurrency deposits into your customers’ 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.

PrerequisitesCopied!

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)

• A verified customer (from the Create and Manage Customers Guide).

Step 1: Get a Quote for the Crypto DepositCopied!

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:

1. Open your terminal or command prompt.

2. Construct a POST request to the /v1/quotes endpoint.

3. Specify the source_currency and target_currency (both being the crypto you expect to receive), the source_amount the customer intends to deposit, and a pay_in object with type: “address” and network.

4. Replace CUSTOMER_ID with your chosen customer’s ID.

5. 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' \
  -H 'X-BU-PROFILE-ID: CUSTOMER_ID' \
  -d '{
    "source_currency": "BTC",
    "target_currency": "BTC",
    "source_amount": "0.0001",
    "pay_in": {
      "type": "address",
      "network": "BTC"
    }
  }'

Expected Quoted Response:

A successful response will return a standard Quote object. Note id of the Quote QUO_JTeZqLxHDQTs in the example data provided) . 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_JTeZqLxHDQTs",
    "profile_id": "CUS_BqpKZiPXPo3Vz",
    "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_JTeZqLxHDQTs",
    "status": "pending",
    "created_at": "2025-06-26T07:07:42.582830829Z",
    "updated_at": "2025-06-26T07:07:42.582830829Z"
  }
}

Note that in the response, the profile_id field is present, indicating the actor of the transaction.

Step 2: Finalize the Deposit Transfer (Generate Crypto Wallet Address) Copied!

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

To finalize the deposit transfer:

1. Use the POST request below to the /v1/transfers endpoint.

2. Include the quote_id obtained from Step 1.

3. Replace CUSTOMER_ID with your chosen customer’s ID.

4. 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' \
  -H 'X-BU-PROFILE-ID: CUSTOMER_ID' \
  -d '{
    "quote_id": "QUO_JTeZqLxHDQTs"
  }'

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_Q4SCEy5Jeblq",
    "profile_id": "CUS_BqpKZiPXPo3Vz",
    "quote_id": "QUO_JTeZqLxHDQTs",
    "description": "Sold BTC",
    "sub_description": "For BTC",
    "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": "tb1qdd7dh2w6q8yth82u727qd7gcvfpa6arrqf8kju",
      "expires_at": "2025-06-26T08:24:00.373863Z",
      "network": "BTC",
      "type": "address"
    },
    "status": "pending",
    "timeline": {
      "total_steps": 0,
      "current_step": 0,
      "transfer_status": "",
      "events": []
    },
    "created_at": "2025-06-26T07:23:59.802433857Z",
    "updated_at": "2025-06-26T07:23:59.80243394Z"
  }
}

Step 3: Instruct Your Customer and Monitor Deposit StatusCopied!

Once you have the crypto wallet address and network details, your application should display these to the customer, along with clear instructions to make the crypto transfer. It is critical to instruct customers to send the exact amount to the correct address on the specified network. After the customer 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_Q4SCEy5Jeblq 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 IssuesCopied!

• “Quote expired” during transfer finalization: Always create a fresh quote immediately before attempting to finalize the transfer.

• Customer sends wrong amount: If the customer sends an amount different from the source_amount specified in the quote, the deposit may fail or be delayed. Advise customers to send the exact amount.

• Customer 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 customer 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.