Exchange Rates API Reference

Use the Exchange Rates API to fetch a real-time exchange rate quote and equivalent amount for a supported currency pair.

All exchange rate requests require a secret key in the Authorization header.

Create Exchange Rate API

API Details

Field	Value
Action	Create Exchange Rate
Method	`POST`
Path	`/v1/exchange-rates`
Auth Requirement	Secret key

Business Summary

This endpoint returns the current exchange rate for a currency pair and the equivalent quote amount for the amount supplied.

You can use this API to:

Show your customers or internal team an estimated equivalent amount.
Preview rates across fiat and crypto currencies supported by Basqet.

Request Parameters

Request Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the form `Bearer sec_...`, using your secret key.
`Content-Type`	string	Yes	Must be `application/json`.
`Idempotency-Key`	string	No	Optional. Reusing the same key within the quote window replays the same response for your account and environment.

Body Parameters

Name	Type	Required	Default	Allowed Values	Description
`base_currency`	string	Yes	-	2-10 character currency slug	Currency slug for the amount you are converting from.
`quote_currency`	string	Yes	-	2-10 character currency slug	Currency slug for the amount you are converting to.
`amount`	number/string	Yes	-	Positive numeric value	Amount denominated in `base_currency`. Strings are accepted when they contain a valid positive number.

Request Example

cURL

curl --request POST \
  --url https://api.basqet.com/v1/exchange-rates \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: rate-preview-1024' \
  --data '{
    "base_currency": "USD",
    "quote_currency": "NGN",
    "amount": "100"
  }'

Response Schema

Field	Type	Nullable	Description
`status`	string	No	Response status. Always `success` for `2xx` responses.
`data`	object	No	Container for the exchange rate quote details.
`data.rate_id`	string	No	Unique exchange rate quote identifier, prefixed with `rate_`.
`data.base_currency`	string	No	Currency slug for the source amount.
`data.quote_currency`	string	No	Currency slug for the equivalent amount.
`data.rate`	number	No	Exchange rate used to calculate `quote_amount`.
`data.base_amount`	number	No	Amount submitted in the request.
`data.quote_amount`	number	No	Equivalent amount in `quote_currency`.
`data.expires_at`	string	No	ISO 8601 timestamp when this rate quote expires.
`data.expiry_in_seconds`	number	No	Number of seconds the rate quote is valid for. Currently `30`.
`data.created_at`	string	No	ISO 8601 timestamp when the rate quote was created.

Sample Response

{
  "status": "success",
  "data": {
    "rate_id": "rate_p8Mz6BnL3rQx2Va",
    "base_currency": "USD",
    "quote_currency": "NGN",
    "rate": 1500,
    "base_amount": 100,
    "quote_amount": 150000,
    "expires_at": "2026-05-15T12:05:30.000Z",
    "expiry_in_seconds": 30,
    "created_at": "2026-05-15T12:05:00.000Z"
  }
}

Same-Currency Example

When the currency pair is the same, Basqet returns a direct 1:1 quote.

{
  "status": "success",
  "data": {
    "rate_id": "rate_V2k8Qp9Lm7Yc4Na",
    "base_currency": "USDT",
    "quote_currency": "USDT",
    "rate": 1,
    "base_amount": 25,
    "quote_amount": 25,
    "expires_at": "2026-05-15T12:05:30.000Z",
    "expiry_in_seconds": 30,
    "created_at": "2026-05-15T12:05:00.000Z"
  }
}

Error Reference

HTTP Code	Message	Resolution
`400`	`INVALID_REQUEST`	Ensure `base_currency`, `quote_currency`, and `amount` are present. `amount` must be a valid positive number.
`400`	`CURRENCY_PAIR_UNSUPPORTED`	The currency does not exist on Basqet or the pair cannot currently be quoted. Try a supported pair or contact Basqet support.
`401`	`No key provided`	Send your secret key in the `Authorization` header.
`403`	`Invalid Key`	Ensure you are using a valid secret key beginning with `sec_`.
`409`	Request already processing	A request with the same `Idempotency-Key` is already being processed. Wait and retry with the same key.
`502`	`INTERNAL_ERROR`	Basqet could not fetch the rate from an upstream rate source. Retry shortly.
`500`	`INTERNAL_ERROR`	An unexpected error occurred while generating the exchange rate. Retry or contact Basqet support.

Validation Error Shape

When request validation fails, Basqet returns field-level errors:

{
  "message": "INVALID_REQUEST",
  "description": "Missing or invalid fields",
  "errors": {
    "amount": {
      "message": "amount must be a valid positive number"
    }
  }
}

Notes

Public keys are not accepted for exchange rate requests.
Rate quotes are short-lived and should be treated as previews, not permanent pricing.
Successful responses are wrapped in a status and data object.
Use quote_amount = base_amount * rate as the mental model for displayed conversions.
Use the Wallet Conversions API when you need to swap between currencies.
Use an Idempotency-Key for retry-safe rate preview requests when your client may retry automatically.