Quotes

At Busha, a Quote is the fundamental building block for nearly every financial operation that involves an asset transfer, such as currency conversions, deposits, or payouts. It precisely describes a proposed asset transfer between a source and a destination, ensuring transparency and accuracy before any funds move. Think of a Quote as a dynamic, real-time snapshot of a proposed transaction. It locks in the terms, such as exchange rates and specific amounts, for a brief period, giving you certainty and control over the outcome of your financial operations.

What is a Quote? The Core Concept

A Quote is a preliminary agreement that describes an asset transfer. Assets can move between:

Busha Balances: Your internal multi-currency accounts on the Busha platform.
External Accounts: Such as crypto wallet addresses, external bank accounts, or mobile money wallets.

Every Quote, at its most basic level, specifies four crucial values that define the proposed transfer:

source_currency: The currency you’re sending (e.g., BTC, NGN).
target_currency: The currency you’re receiving (e.g., NGN, USD).
source_amount: The amount of source_currency to be sent.
target_amount: The amount of target_currency to be received.
quote_currency: The fiat currency (e.g., NGN, KES) that the user wants to use as a reference point for the value of their transaction. It’s the currency in which the user thinks about the desired value of their crypto.
quote_amount: The specific amount of the quote_currency that the user wishes to transact.

Key Properties of a Busha Quote Explained

When you request a Quote from the Busha API, the response contains several key properties that detail the proposed transaction. Understanding these components is essential for working with Busha’s transaction flow:

Source, destination, and their amounts

A Quote always involves a source_currency (the asset being sent) and a target_currency (the asset being received). Crucially, when you request a Quote, you specify either the source_amount or the target_amount, but never both.

If you specify source_amount (e.g., “I want to send 0.001 BTC”), Busha calculates the target_amount (how much NGN you’ll receive) based on the current exchange rate.
If you specify target_amount (e.g., “I want to receive 10,000 NGN”), Busha calculates the source_amount (how much BTC you need to send) based on the current exchange rate.

The Quote response will then provide both the calculated source_amount and target_amount values for the proposed transfer.

Quote currency and quote amount

When you provide quote_currency and quote_amount, Busha takes on the responsibility of calculating either the source_amount (how much crypto you need to send) or the target_amount (how much crypto you will receive). This calculation is performed dynamically based on the current, real-time exchange rates between the specified source_currency, target_currency, and the quote_currency.

Key benefits and purpose

Simplified User Experience: Users no longer need to manually calculate how much crypto they need to buy or sell to achieve a specific fiat value. They simply state the fiat value they’re aiming for.
Fiat-Centric Transactions: This feature caters to users who think about their crypto transactions in terms of their local fiat currency. For example, instead of saying “I want to buy 0.005 BTC,” they can say “I want to buy ₦50,000 worth of BTC.”
Automatic Amount Calculation: The system handles the complex and often fluctuating nature of exchange rates, ensuring the user gets the correct amount of crypto for their desired fiat value, or vice versa.
Inclusion of Fees (for external transfers): When pay_out is an external address, the system will factor in network fees into its calculation, ensuring that the quote_amount is accurately reflected in the final crypto amount.

Restrictions and Requirements:

quote_currency must be fiat: This parameter is strictly for national currencies (e.g., NGN, KES).
source_currency must be crypto when using quote_currency/quote_amount: This implies that this feature is primarily for scenarios where users are converting fiat value into crypto, or using crypto to achieve a specific fiat value.
target_currency can be crypto or fiat: This provides flexibility, allowing users to either receive crypto or convert their crypto to fiat, all while specifying their desired value in a fiat quote_currency.

Transfer channels (`pay_in` and `pay_out`)

While the core of a Quote defines what is being transferred (currencies and amounts), the optional pay_in and pay_out objects specify how the transfer will be facilitated.

pay_in: Provides details about where the source currency will be sent in from.
pay_out: Provides details about the destination of the target currency.

Including these details in the Quote request allows Busha to accurately estimate costs and provide the correct instructions for the specific transfer method.

If either of the pay_in and pay_out objects are not included in the quote object; Busha assumes that the operation is to be executed from the balance.

The transfer channels currently supported are:

Cryptocurrency address
Bank transfers (Nigeria)
Mobile money (Kenya)

The `pay_in` object

The fields in the pay_in object differ from transfer channel to transfer channel. Account balance

"pay_in": {
  "type": "balance"
}

Key	Description	Value
`type`	Specifies the payment type.	`”balance”`

Cryptocurrency channel

"pay_in": {
  "type": "address",
  "network": "BTC"
}

Key	Description	Value
`type`	Specifies the payment type.	`”address”`
`network`	The blockchain network (e.g., Bitcoin, Ethereum).	`”BTC”`

Bank transfer

"pay_in": {
  "type": "temporary_bank_account"
}

Key	Description	Value
`type`	Specifies the payment type. Funds will be paid into a dynamically generated, temporary bank account.	`”temporary_bank_account”`

Mobile money

"pay_in": {
  "type": "mobile_money",
  "phone": "+254 702288461"
}

Key	Description	Value
`type`	Specifies the payment type.	`”mobile_money”`
`phone`	The mobile number associated with the mobile money account for deposit.	`”+254 702288461”`

The `pay_out` object

The fields in the pay_out object differ from transfer channel to transfer channel.

For mobile transfer and mobile money payouts, the recipient should be registered within your Busha business account.

Cryptocurrency

{
  "type": "address",
  "address": "tb1qzw4ynldc55lpkx3vcsk03susv9nwzj6qp78qsq",
  "network": "BTC",
  "memo": ""
}

Key	Description	Value
`type`	Specifies the payout type.	`”address”`
`address`	The cryptocurrency address for the payout.	`”tb1qzw4ynldc55lpkx3vcsk03susv9nwzj6qp78qsq”`
`network`	The blockchain network (e.g., Bitcoin, Ethereum) for the payout.	`”BTC”`
`memo`	An optional field for networks that require a memo/tag/destination tag.

Bank transfer

{
  "type": "bank_transfer",
  "recipient_id": "677bbf9c7cf061f23784555a"
}

Key	Description	Value
`type`	Specifies the payout type.	`”bank_transfer”`
`recipient_id`	The ID of the pre-registered bank account recipient for the payout.	`”677bbf9c7cf061f23784555a”`

Mobile money

{
  "type": "mobile_money",
  "recipient_id": "677bbf9c7cf061f23784555a"
}

Key	Description	Value
`type`	Specifies the payout type.	`”mobile_money”`
`recipient_id`	The ID of the pre-registered mobile money recipient for the payout.	`”677bbf9c7cf061f23784555a”`

Rate object

The rate object nested within the Quote response describes the precise exchange value used for the conversion between the source_currency and target_currency at that moment. It typically includes the pair (e.g., BTCNGN), the rate itself, the side of the transaction (e.g., buy or sell from Busha’s perspective), and the type of rate (e.g., FIXED). This rate is fundamental to how Busha validates and calculates the source_amount and target_amount.

Fees object

The fees object within the Quote response represents any service charges or amounts that will be deducted from the source_amount (or sometimes the target_amount, depending on the transaction type) when the Quote is executed. This provides full transparency on transaction costs.

Quote validity and expiration

Quotes are valid for 3 minutes from creation. After that, they expire and transfers can no longer be created from them. Check the quote’s expires_at before creating a transfer; request a new quote if it has expired. If a transfer is successfully created before the quote expires, its rate is honoured for the remainder of the same 3-minute quote validity window. Creating a transfer does not start a new window. For transfers involving deposits, ensure the deposit is received within that window to honour the quoted rate. Deposits received outside the window are settled at the market rate. Creating the transfer in time alone does not guarantee the quoted rate for a late deposit.

Example of a Quote object

Here is a typical structure of a Quote object that you would receive from the Busha API. This example illustrates a proposed “sell” operation (where you’re selling BTC to get NGN):

{
  "status": "success",
  "message": "Created quote successfully",
  "data": {
    "id": "QUO_uNiw1CDqGrdIlK15N0bu1",
    "profile_id": "BUS_VI3eUQSbGBx4EQuQWYDU1",
    "source_currency": "BTC",
    "target_currency": "NGN",
    "source_amount": "0.00007051",
    "target_amount": "10050.58",
    "rate": {
      "product": "BTCNGN",
      "rate": "142541279.55",
      "side": "sell",
      "type": "FIXED",
      "source_currency": "BTC",
      "target_currency": "NGN"
    },
    "fees": [],
    "reference": "QUO_uNiw1CDqGrdIlK15N0bu1",
    "status": "pending",
    "expires_at": "2025-02-20T06:30:05.059464+01:00",
    "created_at": "2025-02-20T06:27:05.059464+01:00",
    "updated_at": "2025-02-20T06:27:05.059464+01:00"
  }
}

This example represents a sell operation for BTC to your NGN Busha balance, where you specified the desired target_amount in NGN, and the API calculated the source_amount in BTC required.

Why Quotes are the Backbone of Busha’s Flow

The reason Quotes are fundamental to Busha’s API is that every transaction that involves an exchange or transfer of assets (e.g., currency conversion, deposit, payouts, buying/selling crypto) must begin with a Quote. By mandating a Quote first, Busha ensures:

Rate Visibility: You can review the current exchange rate, fees, and calculated amounts before committing. Honour the quoted rate by creating the transfer before the quote expires and, for deposit transfers, ensuring the deposit is received within the same 3-minute quote validity window.
Transparency: All associated costs and conditions are clearly presented within the Quote object.
User Confirmation: Your application can present the precise terms of a transaction to your end-user for their explicit confirmation before proceeding, enhancing trust and preventing errors.
Safety & Pre-validation: A Quote acts as a real-time validation step, confirming that the proposed transaction is valid and executable under current market conditions and system availability, considering the specific transfer methods (pay_in and pay_out) if provided.

Core Concepts

Ramp Widgets

Compliance

What is a Quote? The Core Concept

Key Properties of a Busha Quote Explained

Source, destination, and their amounts

Quote currency and quote amount

Key benefits and purpose

Transfer channels (`pay_in` and `pay_out`)

The `pay_in` object

The `pay_out` object

Rate object

Fees object

Quote validity and expiration

Example of a Quote object

Why Quotes are the Backbone of Busha’s Flow

​What is a Quote? The Core Concept

​Key Properties of a Busha Quote Explained

​Source, destination, and their amounts

​Quote currency and quote amount

​Key benefits and purpose

​Transfer channels (pay_in and pay_out)

​The pay_in object

​The pay_out object

​Rate object

​Fees object

​Quote validity and expiration

​Example of a Quote object

​Why Quotes are the Backbone of Busha’s Flow

What is a Quote? The Core Concept

Key Properties of a Busha Quote Explained

Source, destination, and their amounts

Quote currency and quote amount

Key benefits and purpose

Transfer channels (`pay_in` and `pay_out`)

The `pay_in` object

The `pay_out` object

Rate object

Fees object

Quote validity and expiration

Example of a Quote object

Why Quotes are the Backbone of Busha’s Flow