> ## 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.

# Create Your First Quote

> Learn how to create quotes in Busha. Lock in exchange rates and fees before executing transactions.

This guide will walk you through the essential first step of almost any transaction on Busha: creating a Quote. By generating a Quote, you lock in the terms of a proposed asset transfer, ensuring price certainty and transparency before committing to the transaction.

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

  1. Understand the basic structure for requesting a Quote.

  2. Successfully generate a Quote for a currency conversion.

  3. Learn how to use source\_amount vs target\_amount in your requests.

  4. Explore how to include optional `pay_in` and `pay_out` details in your Quote requests.

  5. Interpret a successful Quote response.
</Tip>

## Prerequisites

Before you begin, ensure you have:

* A Busha Business Account and Secret API Key (from the [Quick Start Tutorial](../getting-started/quick-start)).

* An understanding of API Environments (Sandbox vs. Production) and their base URLs (from the [Make Your First Request Guide](../getting-started/make-first-request)).

* A conceptual understanding of Quotes (from the [Quotes explainer](../../overview/quotes)).

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

## How to Create Your First Quote

<Steps>
  <Step title="Understand Quote Creation Parameters">
    The core of creating a Quote involves specifying the currencies and the amount of the transfer. Remember, you must provide either the `source_amount` or `target_amount`, but not both.

    The essential parameters for creating a quote are:

    <table style={{ width: "100%", borderCollapse: "collapse" }}>
      <thead>
        <tr>
          <th style={{ width: "20%", textAlign: "left", padding: "12px" }}>Parameter</th>
          <th style={{ width: "15%", textAlign: "left", padding: "12px" }}>Data Type</th>
          <th style={{ width: "20%", textAlign: "center", padding: "12px" }}>Required/Optional</th>
          <th style={{ width: "45%", textAlign: "left", padding: "12px" }}>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td style={{ padding: "12px" }}><code>source\_currency</code></td>
          <td style={{ padding: "12px" }}>string</td>
          <td style={{ padding: "12px", textAlign: "center" }}>Required</td>
          <td style={{ padding: "12px" }}>The currency you're sending.</td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}><code>target\_currency</code></td>
          <td style={{ padding: "12px" }}>string</td>
          <td style={{ padding: "12px", textAlign: "center" }}>Required</td>
          <td style={{ padding: "12px" }}>The currency you're receiving.</td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}><code>source\_amount</code></td>
          <td style={{ padding: "12px" }}>string</td>
          <td style={{ padding: "12px", textAlign: "center" }}>Optional</td>
          <td style={{ padding: "12px" }}>The amount of <code>source\_currency</code> you want to send.</td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}><code>target\_amount</code></td>
          <td style={{ padding: "12px" }}>string</td>
          <td style={{ padding: "12px", textAlign: "center" }}>Optional</td>
          <td style={{ padding: "12px" }}>The amount of <code>target\_currency</code> you want to receive.</td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}><code>pay\_in</code></td>
          <td style={{ padding: "12px" }}>object</td>
          <td style={{ padding: "12px", textAlign: "center" }}>Optional</td>
          <td style={{ padding: "12px" }}>Details about the incoming transfer method.</td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}><code>pay\_out</code></td>
          <td style={{ padding: "12px" }}>object</td>
          <td style={{ padding: "12px", textAlign: "center" }}>Optional</td>
          <td style={{ padding: "12px" }}>Details about the outgoing transfer method.</td>
        </tr>
      </tbody>
    </table>
  </Step>

  <Step title="Create a Basic Quote (Conversion Example)">
    Let's create a simple Quote for currency conversion (e.g., converting from NGN to BTC).

    **To create a basic quote:**

    1. Open your terminal or command prompt.

    2. Use the `POST` request below to the `/v1/quotes` endpoint.

    3. Replace `YOUR_BASE_URL` with your chosen environment's URL and `{YOUR SECRET_KEY}` with your actual key.

    4. Choose either source\_amount or `target_amount`. In this example, we'll specify `source_amount`

    ```bash theme={null}
        $ curl -i -X POST https://YOUR_BASE_URL/v1/quotes \
          -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
          -H 'Content-Type: application/json' \
          -d '{
                 "source_currency": "NGN",
                 "target_currency": "BTC",
                 "source_amount": "200000"
              }'
    ```

    **Expected Response:**

    A successful response will return a Quote object, providing the id for this quote, the calculated `target_amount`, the `rate`, `fees`, and the `expires_at` timestamp.

    ```json theme={null}
    {
      "status": "success",
      "message": "Created quote successfully",
      "data": {
        "id": "QUO_AEv8vGiT4jvB",
        "profile_id": "",
        "source_currency": "NGN",
        "target_currency": "BTC",
        "source_amount": "200000",
        "target_amount": "0.00118096",
        "rate": {
          "product": "BTCNGN",
          "rate": "169353287.78",
          "side": "buy",
          "type": "FIXED",
          "source_currency": "NGN",
          "target_currency": "BTC"
        },
        "fees": [],
        "reference": "QUO_AEv8vGiT4jvB",
        "status": "pending",
        "expires_at": "2025-06-10T08:37:56.721186819Z",
        "created_at": "2025-06-10T08:07:26.721165473Z",
        "updated_at": "2025-06-10T08:07:56.721165473Z"
      }
    }
    ```

    <Info>
      1. Note the `id` of the Quote. You'll use this id to execute the transaction (e.g., conversion, deposit, or payout) in a subsequent step.

      2. Check `expires_at`: Always ensure that the quote's `expires_at` time has not passed before attempting to use it.
    </Info>
  </Step>

  <Step title="Understanding Currency-Specific Differences">
    While the quote creation process is the same across currencies, **payment methods differ by country**:

    ### Currency Specific Differences

    <table style={{ width: "100%", borderCollapse: "collapse" }}>
      <thead>
        <tr>
          <th style={{ width: "25%", textAlign: "left", padding: "12px" }}>Aspect</th>
          <th style={{ width: "37.5%", textAlign: "left", padding: "12px" }}>Nigeria (NGN)</th>
          <th style={{ width: "37.5%", textAlign: "left", padding: "12px" }}>Kenya (KES)</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td style={{ padding: "12px" }}><strong>Currency</strong></td>
          <td style={{ padding: "12px" }}>NGN (Naira)</td>
          <td style={{ padding: "12px" }}>KES (Kenyan Shilling)</td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}><strong>Deposit Method</strong></td>
          <td style={{ padding: "12px" }}>Bank transfer to business account</td>
          <td style={{ padding: "12px" }}>M-Pesa or mobile money</td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}><strong>Payout Method</strong></td>
          <td style={{ padding: "12px" }}>Bank transfer</td>
          <td style={{ padding: "12px" }}>M-Pesa or bank transfer</td>
        </tr>
      </tbody>
    </table>

    ### Example: Creating a KES Quote

    The API call structure is identical, just with different currency and amount:

    ```bash theme={null}
        $ curl -i -X POST https://YOUR_BASE_URL/v1/quotes \
          -H 'Authorization: Bearer {YOUR_SECRET_KEY}' \
          -H 'Content-Type: application/json' \
          -d '{
                 "source_currency": "KES",
                 "target_currency": "BTC",
                 "source_amount": "50000",
                 "pay_in": {
                   "type": "mobile_money",
                   "phone": "+254712345678"
                 }
              }'
    ```

    <Accordion title="View KES Quote Response">
      ```json theme={null}
      {
        "status": "success",
        "message": "Created quote successfully",
        "data": {
          "id": "QUO_KES123Example",
          "source_currency": "KES",
          "target_currency": "BTC",
          "source_amount": "50000",
          "target_amount": "0.00029123",
          "rate": {
            "product": "BTCKES",
            "rate": "171680500.00",
            "side": "buy",
            "type": "FIXED",
            "source_currency": "KES",
            "target_currency": "BTC"
          },
          "fees": [],
          "expires_at": "2025-06-10T08:37:56.721186819Z",
          "created_at": "2025-06-10T08:07:26.721165473Z",
          "updated_at": "2025-06-10T08:07:56.721165473Z"
        }
      }
      ```
    </Accordion>

    <Note>
      For currency-specific payment method details, see:

      * [Process Fiat Deposits](../deposits/process-fiat-deposits) for bank vs mobile money
      * [Create Recipients](../recipients/create-and-manage) for payment method setup
    </Note>
  </Step>

  <Step title="Create a Quote with `pay_in` Details (for Deposits)">
    For certain transaction types like deposits (PayIns) or direct crypto purchases, you might need to specify details about the incoming payment method using the `pay_in` object in your quote request. This helps Busha generate accurate deposit instructions.

    **To create a quote for a deposit (e.g., crypto):**

    1. Use a `POST` request to `/v1/quotes` as before.

    2. Include the `pay_in` object with relevant details. For a crypto deposit, this might include the `network`.

    ```bash theme={null}
        $ 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": "NGN",
            "target_amount": "50000",
            "pay_in": {
              "type": "address",
              "network": "BTC"
            }
        }'
    ```

    **Expected Response**

    The Quote response itself will be similar to the basic one, with the `pay_in` object included in the response.

    ```json theme={null}
    {
      "status": "success",
      "message": "Created quote successfully",
      "data": {
        "id": "QUO_mwdzbJiiAUa7",
        "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
        "source_currency": "BTC",
        "target_currency": "NGN",
        "source_amount": "0.00029895",
        "target_amount": "50000",
        "rate": {
          "product": "BTCNGN",
          "rate": "167252998.89",
          "side": "sell",
          "type": "FIXED",
          "source_currency": "BTC",
          "target_currency": "NGN"
        },
        "fees": [],
        "pay_in": {
          "network": "BTC",
          "type": "address"
        },
        "reference": "QUO_mwdzbJiiAUa7",
        "status": "pending",
        "expires_at": "2025-06-10T08:46:54.461965014Z",
        "created_at": "2025-06-10T08:16:54.461945463Z",
        "updated_at": "2025-06-10T08:16:54.461945463Z"
      }
    }
    ```
  </Step>

  <Step title="Create a Quote with `pay_out` Details (for Payouts/Withdrawals)">
    When initiating a payout (withdrawal) from your Busha account, you'll need to specify details about the outgoing payment method using the `pay_out` object. This guides Busha on where and how to send the funds. This also typically requires a `recipient_id`.

    **To create a quote for a payout**

    <Info>
      For payouts to bank accounts, ensure you have a `recipient_id` for the bank
      account you wish to pay out to. (Refer to: [How to Create and Manage
      Recipients Guide](../recipients/create-and-manage))
    </Info>

    1. Use a POST request to `/v1/quotes`.

    2. Include the `pay_out` object with details for the target recipient and channel.

    ```bash theme={null}
        $ 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",
                "target_amount": "0.0001",
                "pay_out": {
                  "type": "address",
                  "network": "BTC",
                  "address": "tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr"
                }
           }'
    ```

    **Expected Response:**

    The Quote response itself will be similar to the basic one, with the `pay_out` object included in the response.

    ```json theme={null}
    {
      "status": "success",
      "message": "Created quote successfully",
      "data": {
        "id": "QUO_0OF0pBoXllc0",
        "profile_id": "BUS_jlKUYwF9z1ynQZ98bWbaP",
        "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": [
          {
            "amount": {
              "amount": "0.000005",
              "currency": "BTC"
            },
            "name": "network fee",
            "type": "FIXED"
          }
        ],
        "pay_out": {
          "address": "tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr",
          "network": "BTC",
          "type": "address"
        },
        "reference": "QUO_0OF0pBoXllc0",
        "status": "pending",
        "created_at": "2025-06-10T08:35:34.224940272Z",
        "updated_at": "2025-06-10T08:35:34.224940272Z"
      }
    }
    ```
  </Step>
</Steps>

## Troubleshooting Common Quote Creation Issues

* **"Quote expired"** in subsequent transactions: The quote ID you received was valid when created, but expired before you used it. Always generate a fresh quote immediately before executing the transaction.

* **"One of target and source amount must be set"**: You included both `source_amount` and `target_amount` in your request. Remove one.

* **`401 Unauthorized`**: Double-check that your secret API key is correct.

## What's Next?

Once you have successfully created a Quote, the next step is to execute the actual transaction based on that Quote.

* [How to Get a Quote](./get-quote)

* [How to Process Fiat Deposits (PayIns) Guide](../deposits/process-fiat-deposits)

* [How to Process Crypto Deposits (PayIns) Guide](../deposits/process-crypto-deposits)

* [How to Make Payouts Guide](../payouts/process-payouts)

* [How to Perform Currency Conversions Guide](../balance/convert-balance-to-balance)

* [API Reference: Quote Object](../../api-reference/quotes/create-a-new-quote): For a complete list of all parameters, sub-fields for `pay_in` and `pay_out`, and their data types.