Convert from Balance to Balance

This guide will show you how to programmatically convert one cryptocurrency into another within your Busha Business account (e.g., USDT to BTC). All conversions on Busha are processed as transfers, which always begin with a Quote to define the conversion terms.

What You’ll Achieve:

Understand the specific quote requirements for crypto conversions.
Generate a conversion quote.
Execute the crypto-to-crypto conversion transfer.
Confirm the status of the conversation.

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)

Step 1: Create a Conversion QuoteCopied!

The first step in any conversion is to create a Quote. This specifies the source_currency (what you're converting from) and target_currency (what you're converting to). You must provide either the source_amount or the target_amount, but not both.

To create a conversion quote:

Open your terminal or command prompt.
Construct a POST request to the /v1/quotes endpoint.
Specify the source_currency, target_currency, and either source_amount (as shown below) or target_amount. Make sure to set the type to "convert".
Replace YOUR_BASE_URL with your chosen environment's URL, YOUR_SECRET_TOKEN with your actual key, and BUS_YOK8tp5Zga01qOKEsqp07 with your actual X-BU-PROFILE-ID.

$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/quotes \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'X-BU-PROFILE-ID: BUS_YOK8tp5Zga01qOKEsqp07' \
  -d '{
    "source_currency": "USDT",
    "target_currency": "BTC",
    "source_amount": "20"
  }'

Expected Quote Response:

A successful response will return a Quote object containing the id, calculated target_amount (if you provided source_amount), the rate for the conversion, and its expires_at timestamp. Note the id of this quote (e.g., QUO_Nm2EBRxmuHGdTyGnVNDUt), as you'll need it for the next step.

Step 2: Create the Conversion TransferCopied!

Once you have a valid Quote ID, you can proceed to execute the conversion by creating a transfer. This action consumes the quote and initiates the actual asset exchange.

To create the conversion transfer:

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

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

Expected Transfer Response:

A successful response indicates that the transfer has been initiated. For conversions, the transaction is typically processed very quickly, often immediately. The response will include a id (e.g., TRF_oBoehqd2KVt1wcadB8wz5) and the initial status of the transfer (likely pending or completed almost instantly).

Step 3: Confirm TransferCopied!

Although conversion transfers are usually processed immediately, it's good practice to confirm their final status. You can do this by retrieving the transfer details using its ID.

To confirm the transfer status:

Use the GET request below to the /v1/transfers/{id} endpoint.
Replace {id} with the actual transfer_id you received in Step 2.
Replace YOUR_BASE_URL and YOUR_SECRET_TOKEN with your actual details.

$ curl -i -X GET \
  https://YOUR_BASE_URL/v1/transfers/TRF_oBoehqd2KVt1wcadB8wz5 \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'

Expected Statuses:

completed: The conversion was successful, and your target_currency balance has been updated.
failed: The conversion failed (e.g., insufficient balance, quote expired before execution).
pending: (Less common for conversions, but possible briefly) The transfer is still being processed.

For real-time updates, setting up webhooks is recommended, as they will notify you automatically when the transfer status changes.

A trade is a type of conversion that represents a buy or sell action from or to Busha Fiat Wallet against a Busha crypto asset.

A trade works just the same as a conversion, except that either of the source_currency and target_currency could be a fiat currency (e.g., NGN, KES).

Troubleshooting Common Conversion Issues:Copied!

"Quote expired" during transfer creation: Always generate a fresh quote immediately before attempting to create the transfer.
"Insufficient balance": Ensure your Busha account has enough source_currency to cover the source_amount in the quote.
Invalid currency pair: Double-check that Busha supports direct conversion between your chosen source_currency and target_currency.
401 Unauthorized: Verify your Authorization header and API key.

What's Next?Copied!

Now that you understand balance-to-balance conversions, you can explore other transaction types: