GuideReference

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.

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.

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 the incoming payment method for a deposit or fund transfer into your Busha account. This might include specific bank account details for a fiat deposit or a crypto network for a crypto deposit.

  • pay_out: Provides details about the outgoing payment method for a payout or fund transfer from your Busha account. This could involve specific bank account details for a fiat payout or a crypto wallet address for a crypto withdrawal.

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

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: