Exchange Rate (Buy and Sell)

Returns the current exchange rate for a supported currency pair and calculates the expected converted amount based on the selected transaction side.

This endpoint can be used to retrieve either the BUY or SELL rate for a supported swap pair.

Endpoint

Method: GET

{{base_url}}/api/v1/swap/rate

Authentication

Bearer Token: Required

Headers

Query Parameters

Example Request

The following example shows a request using NGN and EUSD:MOB. The actual currencies should be selected from the swap pairs supported by LedgerBlock.

curl --request GET \
  --url '{{base_url}}/api/v1/swap/rate?base_currency=NGN&quote_currency=EUSD:MOB&amount=1&side=SELL' \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --header 'x-merchant-ref: {{x_merchant_ref}}'

Response

{
  "status": "success",
  "message": "Swap rate",
  "data": {
    "base_currency": "NGN",
    "quote_currency": "EUSD:MOB",
    "side": "BUY",
    "rate": 1700,
    "amount": 1,
    "converted_amount": 0.0005882352941176
  }
}

Response Parameters

How It Works

The Exchange Rate endpoint allows a merchant to determine how much of the quote currency will be received or how much of the base currency is required for a swap.

The merchant provides:

• The base_currency
• The quote_currency
• The amount
• The side (BUY or SELL)

LedgerBlock then returns the applicable exchange rate and the resulting converted_amount.

The currencies used in the request are not fixed. Merchants should use currencies and currency pairs that are currently supported by LedgerBlock.

The supported swap pairs can be retrieved from the Platform Available Pairs endpoint.

BUY Rate

A BUY rate is used when the merchant is buying the quote currency.

Example fl;or a pair where the BUY rate is:

1 Quote Currency = 1,700 Base Currency

the conversion can be represented as:

Base Currency Amount ÷ BUY Rate = Quote Currency Amount

For example:

Amount: 17,000 NGN
BUY Rate: 1,700

17,000 ÷ 1,700 = 10 EUSD:MOB

Therefore:

17,000 NGN = 10 EUSD:MOB

SELL Rate

A SELL rate is used when the merchant is selling the relevant asset and receiving the other currency.

For example, if the applicable SELL rate is:

1 EUSD:MOB = 1,490 NGN

the conversion can be represented as:

Quote Currency Amount × SELL Rate = Base Currency Amount

For example:

Amount: 10 EUSD:MOB
SELL Rate: 1,490

10 × 1,490 = 14,900 NGN

Therefore:

10 EUSD:MOB = 14,900 NGN

Rate Example

Assume LedgerBlock returns the following available pair:

{
  "base_currency": "NGN",
  "quote_currency": "EUSD:MOB",
  "buy_rate": 1700,
  "sell_rate": 1490
}

The two rates have different purposes.

BUY

1 EUSD:MOB = 1,700 NGN

To determine the amount of EUSD:MOB received when buying it with NGN:

NGN Amount ÷ 1,700 = EUSD:MOB Amount

Example:

17,000 NGN ÷ 1,700 = 10 EUSD:MOB

SELL

1 EUSD:MOB = 1,490 NGN

To determine the amount of NGN received when selling EUSD:MOB:

EUSD:MOB Amount × 1,490 = NGN Amount

Example:

10 EUSD:MOB × 1,490 = 14,900 NGN

Supported Currencies

The base_currency and quote_currency values should always be selected from currencies and currency pairs currently supported by LedgerBlock.

Do not assume that a particular currency is always available. Merchants should first retrieve the currently active pairs using the Platform Available Pairs endpoint.

For example, LedgerBlock may support pairs such as:

NGN → CAD
NGN → USDT
NGN → EUSD:MOB
NGN → USDT:POL
USDT:POL → EUSD:MOB

The actual supported pairs should be determined from the response returned by the Platform Available Pairs endpoint.

Conversion Logic

The exchange rate should be interpreted together with the requested side.

For a BUY transaction:

Converted Amount = Base Amount ÷ Buy Rate

For a SELL transaction:

Converted Amount = Quote Amount × Sell Rate

However, merchants should use the converted_amount returned by the API as the final value for the requested rate calculation rather than relying solely on client-side calculations.

Request and Response Example

Request

GET {{base_url}}/api/v1/swap/rate

Query parameters:

base_currency=NGN
quote_currency=EUSD:MOB
amount=1
side=SELL

Response

{
  "status": "success",
  "message": "Swap rate",
  "data": {
    "base_currency": "NGN",
    "quote_currency": "EUSD:MOB",
    "side": "BUY",
    "rate": 1700,
    "amount": 1,
    "converted_amount": 0.0005882352941176
  }
}

Important Notes

• The currencies in the request are dynamic and must be supported by LedgerBlock.
• The endpoint should be used with active currency pairs returned by the Platform Available Pairs endpoint.
• BUY and SELL rates may differ for the same currency pair.
• The rate returned by this endpoint is the rate applicable to the requested conversion.
• The converted_amount is the amount calculated by LedgerBlock for the supplied request.
• Merchants should use the API response as the authoritative result when displaying or processing a conversion.
• Currency values that include a network identifier, such as USDT:POL or EUSD:MOB, should be passed exactly as returned by the platform.

API Response Consistency

In the provided example, the request specifies:

side=SELL

while the response contains:

"side": "BUY"

This indicates a difference between the requested side and the side returned in the sample response.

The exact expected behavior should be confirmed with the LedgerBlock API implementation before merchants rely on the response side field for transaction logic.