Skip to main content
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.
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.

​
Prerequisites

Before you begin, ensure you have:
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.

​
How to Create Your First Quote

1

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:
ParameterData TypeRequired/OptionalDescription
source_currencystringRequiredThe currency you’re sending.
target_currencystringRequiredThe currency you’re receiving.
source_amountstringOptionalThe amount of source_currency you want to send.
target_amountstringOptionalThe amount of target_currency you want to receive.
pay_inobjectOptionalDetails about the incoming transfer method.
pay_outobjectOptionalDetails about the outgoing transfer method.
2

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 
$ 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.
{
  "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"
  }
}
  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.
3

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. 
$ 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 ResponseThe Quote response itself will be similar to the basic one, with the pay_in object included in the response.
{
  "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"
  }
}
4

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
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)
  1. Use a POST request to /v1/quotes.
  2. Include the pay_out object with details for the target recipient and channel. 
$ 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.
{
  "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"
  }
}

​
Troubleshooting Common Quote Creation Issues

  • “Quote expired” in subsequent transaction: 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.