Wallet Conversions Overview

Wallet conversions let you move value between supported Basqet wallet currencies. When you convert, Basqet debits your source wallet, credits your destination wallet, we also record the conversion details so you can reconcile the movement later.

Use wallet conversions when you already have funds in one Basqet wallet and want those funds available in another supported currency.

How Wallet Conversions Work

A wallet conversion has two steps:

Create a conversion quote
Execute the conversion with the quote

The quote tells you how much will leave your source wallet, how much you should receive in your destination wallet, the exchange rate, and when the quote expires.

After you accept the quote by creating the conversion, Basqet updates your wallet balances and returns a conversion record.

Conversion quotes are short-lived(10 secs). Create the conversion immediately after receiving a quote, and do not reuse a quote after a successful conversion.

When To Use Wallet Conversions

Wallet conversions are useful when you need to:

Use Case	Description
Rebalance wallet balances	Move funds from one supported wallet currency into another.
Prepare funds for payouts or operations	Convert funds into the currency you need before using them elsewhere.
Manage currency exposure	Reduce the amount you hold in one currency by converting to another.
Reconcile treasury movement	Use conversion IDs and your own reference values to track internal wallet movements.

Supported Conversion Currencies

Wallet conversions currently support these currency slugs:

Currency	Description
`NGN`	Nigerian Naira
`USDT`	Tether
`BTC`	Bitcoin
`ETH`	Ethereum
`LTC`	Litecoin
`QDX`	Quidax Token
`USDC`	USD Coin

Both from_currency and to_currency must be supported, and they must be different.

Before You Start

Before creating wallet conversions, make sure:

You have a Basqet secret key in the form sec_....
Your source wallet has enough available balance.
You know the currency slug you want to convert from and the currency slug you want to convert to.
Your system can create a quote and then execute the conversion immediately.
Your system can safely retry conversion requests with an Idempotency-Key.

Recommended Integration Flow

Choose the source currency, destination currency, and amount.
Create a conversion quote with POST /v1/wallets/conversions/quotes.
Show or review the quoted amount and exchange rate.
Execute the conversion with POST /v1/wallets/conversions using the returned quote_id.
Store the returned conversion_id, rate_id, reference, from_amount, to_amount, and rate_used.
Use GET /v1/wallets/conversions to retrieve conversion history when you need reconciliation data.

References And Idempotency

You can pass a reference when creating a conversion. Use this to store your own internal conversion ID, order ID, or treasury operation ID.

When supplied, reference must be unique for your account.

You should also send an Idempotency-Key when creating conversions. This helps protect you from duplicate conversions if your client times out or retries a request.

Wallet Updated Webhooks

When a conversion succeeds and your wallet balances are updated, Basqet may send wallet.updated webhooks to your configured webhook URL.

A successful conversion usually produces:

One wallet update for the wallet that was debited.
One wallet update for the wallet that was credited.

Use the transaction_reference in the webhook payload to connect wallet updates back to the conversion_id.

Important Notes

A conversion quote can only be used once.
Quotes and conversions cannot be shared across test and live environments.
Basqet processes only one wallet conversion at a time for your account to protect wallet balances from race conditions.
Use the Exchange Rates API if you only need a rate preview and do not want to move wallet balances.