> ## Documentation Index
> Fetch the complete documentation index at: https://docs.busha.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert Between Balances

> Convert funds between currencies in your Busha account. Swap NGN to USDT, BTC to KES, and more.

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.

<Tip>
  **What You'll Achieve:**

  1. Understand the specific quote requirements for crypto conversions.
  2. Generate a conversion quote.
  3. Execute the crypto-to-crypto conversion transfer.
  4. Confirm the status of the conversation.
</Tip>

## Prerequisites

Before you begin, ensure you have:

* A **Busha Business Account** and **Secret API Key** (from the [Quick Start Tutorial](/guides/getting-started/quick-start))
* An understanding of the **API Environments** (Sandbox vs. Production) and their respective base URLs (from the [Make Your First Request Guide](/guides/getting-started/make-first-request)).
* A conceptual understanding of **Quotes** (from the [Understanding Quotes](/overview/quotes) Overview).
* Familiarity with creating basic quotes (from the [How to Create Your First Quote](/guides/quotes/create-first-quote) Guide).

<Note>
  For conversion 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.
</Note>

## How to Convert Crypto to Crypto

<Steps>
  <Step title="Create a Conversion Quote">
    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:

    1. Open your terminal or command prompt.
    2. Construct a `POST` request to the `/v1/quotes` endpoint.
    3. Specify the `source_currency`, `target_currency`, and either `source_amount` (as shown below) or `target_amount`. Make sure to set the type to "convert".
    4. 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`.

    ```bash theme={null}
    $ 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>

  <Step title="Create the Conversion Transfer">
    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:

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

    ```bash theme={null}
    $ 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>

  <Step title="Confirm Transfer">
    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:

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

    ```bash theme={null}
    $ 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.
  </Step>
</Steps>

<Info>
  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).
</Info>

## Troubleshooting

**Common Conversion Issues:**

* **"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?

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

* [How to Create Your First Quote Guide](/guides/quotes/create-first-quote)
* [How to Process Fiat Deposits Guide](/guides/deposits/process-fiat-deposits)
* [How to Process Crypto Deposits Guide](/guides/deposits/process-crypto-deposits)
* [Quotes API Reference](/api-reference/quotes/list-quotes)
* [Transfers API Reference](/api-reference/transfers/list-transfers)