> ## 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. # Quotes > Learn how quotes work in Busha. Lock in exchange rates and fees before executing transactions. 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 1. **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. 2. **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." 3. **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. 4. **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** ```json theme={null} "pay_in": { "type": "balance" } ```
Key Description Value
type Specifies the payment type. "balance"
**Cryptocurrency channel** ```json theme={null} "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** ```json theme={null} "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** ```json theme={null} "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** ```json theme={null} { "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** ```json theme={null} { "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** ```json theme={null} { "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 expiration (expires\_at) **All Quotes expire!** Every Quote object includes an `expires_at` timestamp. This specifies the exact time after which the Quote becomes invalid and can no longer be used to make any transfers. Quotes typically have a short validity period (e.g., a few seconds to a few minutes) to account for volatility in market prices, especially for cryptocurrencies. If you attempt to execute a transaction with an expired Quote, the request will be executed at the current market price. ### 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): ```json theme={null} { "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:57:05.059512+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: * **Price Certainty:** You know the exact exchange rate, fees, and final amounts before committing to any transaction. This eliminates surprises. * **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.