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

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

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.

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

  plaintext Copy Copied!

  Key	Description	Value
  type	Specifies the payment type.	"balance"

• Cryptocurrency channel

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

  json Copy Copied!

  Key	Description	Value
  type	Specifies the payment type.	"address"
  address	The cryptocurrency address for the deposit.	"tb1q9j29ymzg2wg9c40es4pkq683ua7h79nscn742l"
  network	The blockchain network (e.g., Bitcoin, Ethereum).	"BTC"

• Bank transfer

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

  json Copy Copied!

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

  json Copy Copied!

  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.

• Cryptocurrency

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

  json Copy Copied!

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

  json Copy Copied!

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

  json Copy Copied!

  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):

{
  "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 FlowCopied!

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.

What’s Next?Copied!

Now that you understand the concept of Quotes, you can proceed to learn how to integrate them into your application’s transaction flows: