GuideReference

Create Your First Quote

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.

PrerequisitesCopied!

Before you begin, ensure you have:

Step 1: Understand Quote Creation ParametersCopied!

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:

Parameter

Data Type

Required/Optional

Description

source_currency

string

Required

The currency you’re sending.

target_currency

string

Required

The currency you’re receiving.

source_amount

string

Optional

The amount of source_currency you want to send.

target_amount

string

Optional

The amount of target_currency you want to receive.

pay_in

object

Optional

Details about the incoming transfer method.

pay_out

object

Optional

Details about the outgoing transfer method.

Step 2: Create a Basic Quote (Conversion Example)Copied!

Let’s create a simple Quote for currency conversion (e.g., converting from USDT 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.

Step 3: Creating a Quote with pay_in Details (for Deposits)Copied!

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",
      "address": "tb1q9j29ymzg2wg9c40es4pkq683ua7h79nscn742l",
      "network": "BTC"
  }
}'

Expected Response

The 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"
  }
}

Step 4: Creating a Quote with pay_out Details (for Payouts/Withdrawals)Copied!

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 IssuesCopied!

  • “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?Copied!

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