Wallet Conversions API Reference

Use the Wallet Conversions API to quote, execute, and list conversions between your supported Basqet wallet currencies.

All wallet conversion endpoints require a secret key in the Authorization header.

Before you proceed make sure you've read about how conversions work on Basqet

1. Create Conversion Quote API

API Details

Field	Value
Action	Create Conversion Quote
Method	`POST`
Path	`/v1/wallets/conversions/quotes`
Auth Requirement	Secret key

Business Summary

This endpoint generates a real-time quote for converting one wallet currency to another. The response includes the source amount, destination amount, exchange rate, and quote expiry time.

You can use this API to:

See the exact amount you will receive before converting.
Lock a temporary quote for a supported currency pair.
Get the quote_id required to create the final conversion.

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`.

Body Parameters

Name	Type	Required	Default	Allowed Values	Description
`from_currency`	string	Yes	-	`NGN`, `USDT`, `BTC`, `ETH`, `LTC`, `QDX`, `USDC`	Currency slug of the wallet to debit.
`to_currency`	string	Yes	-	`NGN`, `USDT`, `BTC`, `ETH`, `LTC`, `QDX`, `USDC`	Currency slug of the wallet to credit. Must be different from `from_currency`.
`amount`	number	Yes	-	Number greater than `0`	Amount to convert from your source wallet.

Request Example

cURL

curl --request POST \
  --url https://api.basqet.com/v1/wallets/conversions/quotes \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "from_currency": "NGN",
    "to_currency": "USDT",
    "amount": 14000
  }'

Response Schema

Field	Type	Nullable	Description
`status`	string	No	Response status. Always `success` for `2xx` responses.
`data`	object	No	Container for the quote details.
`data.quote_id`	string	No	Unique quote identifier. Use this as `quote_id` when creating the conversion.
`data.from_currency`	string	No	Source wallet currency slug.
`data.to_currency`	string	No	Destination wallet currency slug.
`data.from_amount`	number	No	Amount to debit from your source wallet.
`data.to_amount`	number	No	Amount expected to be credited to your destination wallet.
`data.exchange_rate`	number	No	Rate used to calculate `to_amount`.
`data.expires_at`	string	No	ISO 8601 timestamp when the quote expires.

Sample Response

{
  "status": "success",
  "data": {
    "quote_id": "cq_x9R4mL2pQ8sT7vA",
    "from_currency": "NGN",
    "to_currency": "USDT",
    "from_amount": 14000,
    "to_amount": 10,
    "exchange_rate": 0.000714285714285714,
    "expires_at": "2026-05-15T12:05:30.000Z"
  }
}

Error Reference

HTTP Code	Message	Resolution
`400`	`Validation Error`	Ensure `from_currency`, `to_currency`, and `amount` are present. `amount` must be greater than `0`.
`400`	`INVALID_REQUEST`	Ensure both currencies are supported and that `from_currency` and `to_currency` are different.
`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_`.
`500`	`CONVERSION_FAILED`	An unexpected error occurred while generating the quote. Retry the request or contact Basqet support.

2. Execute Conversion API

API Details

Field	Value
Action	Create Wallet Conversion
Method	`POST`
Path	`/v1/wallets/conversions`
Auth Requirement	Secret key

Business Summary

This endpoint executes a wallet conversion using a valid quote. Basqet debits your source wallet, credits your destination wallet, records the conversion, and returns the conversion details.

You can use this API to:

Convert funds from one supported wallet currency to another.
Record your own reference for reconciliation.
Make the converted funds immediately available in your destination wallet when the conversion succeeds.

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	Recommended for safe retries. Reusing the same key returns the cached result for your account and environment.

Body Parameters

Name	Type	Required	Default	Allowed Values	Description
`quote_id`	string	Yes	-	Prefixed with `cq_`	Quote identifier returned by the Create Conversion Quote API.
`reference`	string	No	`null`	Maximum 255 characters	Optional reference from your system. Must be unique for your account when provided.

Request Example

cURL

curl --request POST \
  --url https://api.basqet.com/v1/wallets/conversions \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: conv-request-1024' \
  --data '{
    "quote_id": "cq_x9R4mL2pQ8sT7vA",
    "reference": "order-conv-1024"
  }'

Response Schema

Field	Type	Nullable	Description
`status`	string	No	Response status. Always `success` for `2xx` responses.
`data`	object	No	Container for conversion details.
`data.conversion_id`	string	No	Unique Basqet conversion identifier, prefixed with `conv_`.
`data.rate_id`	string	No	Quote ID used for the conversion.
`data.from_currency`	string	No	Source wallet currency slug.
`data.to_currency`	string	No	Destination wallet currency slug.
`data.from_amount`	number	No	Amount debited from your source wallet.
`data.to_amount`	number	No	Amount credited to your destination wallet.
`data.rate_used`	number	No	Exchange rate used for the conversion.
`data.reference`	string/null	Yes	Reference from your system, or `null` if omitted.
`data.created_at`	string	No	ISO 8601 timestamp of conversion creation.

Sample Response

{
  "status": "success",
  "data": {
    "conversion_id": "conv_p4Y7xN8aK2mR5tQ",
    "rate_id": "cq_x9R4mL2pQ8sT7vA",
    "from_currency": "NGN",
    "to_currency": "USDT",
    "from_amount": 14000,
    "to_amount": 10,
    "rate_used": 0.000714285714285714,
    "reference": "order-conv-1024",
    "created_at": "2026-05-15T12:04:45.000Z"
  }
}

Error Reference

HTTP Code	Message	Resolution
`400`	`Validation Error`	Ensure `quote_id` is present and is a non-empty string.
`400`	`QUOTE_EXPIRED`	Create a new quote and retry the conversion.
`400`	`QUOTE_MISMATCH`	Ensure the quote was created with the same secret key and environment.
`400`	`INSUFFICIENT_BALANCE`	Fund your source wallet or reduce the conversion amount.
`400`	`INVALID_REQUEST`	The request is invalid. This can happen when your reference is already in use or another conversion is already in progress for your account.
`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_`.
`404`	`QUOTE_NOT_FOUND`	The quote does not exist, has expired, was already used, or is no longer available. Create a new quote.
`409`	Request already processing	A request with the same `Idempotency-Key` is already being processed. Wait and retry with the same key.
`500`	`CONVERSION_FAILED`	An unexpected error occurred while executing the conversion. Retry only after checking whether the conversion was created.

3. List Wallet Conversions API

API Details

Field	Value
Action	List Wallet Conversions
Method	`GET`
Path	`/v1/wallets/conversions`
Auth Requirement	Secret key

Business Summary

Returns a paginated list of wallet conversions for your account. Results are returned for the environment tied to the secret key you use.

Request Parameters

Request Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the form `Bearer sec_...`, using your secret key.

Query Parameters

Name	Type	Required	Default	Allowed Values	Description
`limit`	number	No	`50`	Integer from `1` to `100`	Number of records to return.
`offset`	number	No	`0`	Integer greater than or equal to `0`	Number of records to skip.
`reference`	string	No	-	Maximum 255 characters	Filter conversions by your reference.

Request Example

cURL

curl --request GET \
  --url 'https://api.basqet.com/v1/wallets/conversions?limit=20&offset=0&reference=order-conv-1024' \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx'

Response Schema

Field	Type	Nullable	Description
`status`	string	No	Response status. Always `success` for `2xx` responses.
`data`	array	No	Array of conversion objects.
`meta.limit`	number	No	Limit applied to the request.
`meta.count`	number	No	Number of records returned in this page.
`meta.hasNext`	boolean	No	`true` if more records exist beyond this page.

Sample Response

{
  "status": "success",
  "data": [
    {
      "conversion_id": "conv_p4Y7xN8aK2mR5tQ",
      "rate_id": "cq_x9R4mL2pQ8sT7vA",
      "from_currency": "NGN",
      "to_currency": "USDT",
      "from_amount": 14000,
      "to_amount": 10,
      "rate_used": 0.000714285714285714,
      "reference": "order-conv-1024",
      "created_at": "2026-05-15T12:04:45.000Z"
    }
  ],
  "meta": {
    "limit": 20,
    "count": 1,
    "hasNext": false
  }
}

Wallet Updated Webhook

When a conversion succeeds and wallet balances are updated, Basqet may send wallet.updated webhooks to your configured webhook URL. A conversion normally produces one wallet update for the debited wallet and one wallet update for the credited wallet.

Sample Payload

{
  "event": "wallet.updated",
  "data": {
    "wallet": {
      "transaction_reference": "conv_p4Y7xN8aK2mR5tQ",
      "available_balance": 36000,
      "ledger_balance": 0,
      "currency": "NGN",
      "name": "Nigerian Naira",
      "type": "FIAT",
      "amount": 14000,
      "is_live": true
    }
  }
}

Notes

Public keys are not accepted for wallet conversion endpoints.
Use test secret keys for sandbox conversions and live secret keys for live conversions.
Quotes and conversions cannot be shared across environments.
A quote can only be used once. After a successful conversion, the quote cannot be reused.
Send an Idempotency-Key when creating conversions so network retries do not create duplicate conversions.