Tutorial: Swap Bitcoin to USDT or USDC
This tutorial shows you how to convert Bitcoin (BTC) from a user’s Bitnob wallet into USDT or USDC using Bitnob’s built-in swap engine. You’ll go from checking balances to completing a swap and confirming the new stablecoin balance.
This is useful when:
Users want to lock in the value of their BTC
You want to stabilize treasury or float in stablecoins
You’re enabling BTC payments but settling in USDT/USDC
Key Concepts
Swaps allow users to convert volatile assets (BTC) into stable assets (USDT or USDC) inside Bitnob. Bitnob handles the exchange rate matching, balance updates, and fees all through simple API calls.
By default, every Bitnob account has a BTC, USDT, and USDC wallet created automatically. You don’t need to create these.
Prerequisites
A Bitnob sandbox or production API key
The user must have BTC in their wallet (from on-chain or Lightning)
You should track reference IDs for each swap
Step 1: Check BTC Wallet Balance
To confirm the user has sufficient funds to swap, check their BTC balance.
If you're listing all wallets:
From the response, look for the wallet with "currency": "BTC" and check the availableBalance.
Step 2: Get a Swap Quote (Optional)
You can fetch a live rate before executing the swap. This allows you to show the user what they’ll receive.
Example Request
Change toCurrency to "USDC" if you want to swap to USDC instead.
Example Response
The quote expires in 60 seconds. You should show this info to the user (rate, fees, amount they’ll receive) before confirming the swap.
Step 3: Execute the Swap
To perform the conversion, send a swap request.
Example Request
Example Response
This response confirms that the BTC was successfully converted to stablecoin and credited to the appropriate wallet.
Step 4: Confirm Stablecoin Wallet Balance
To verify the updated balance, call:
Based on the currency you swapped into.
The wallet response will include fields like availableBalance,totalReceived , and currency.
Handling Errors
If the user has insufficient BTC, you’ll get a 400 error with a descriptive message
If the quote has expired, you’ll be asked to fetch a new one
If the wallet is locked or unavailable, the swap will fail
Always log the swapId and reference for reconciliation
Best Practices
Always fetch a quote before swapping, especially if you're building a user-facing UI
Show a timer for the quote expiry if you use quotes in the front end
Clearly display fees and rates for transparency
Use unique reference values per swap so you can audit them later Avoid executing back-to-back swaps without confirming balances
Summary
With just a few API calls, you can enable users to:
Convert Bitcoin (on-chain or Lightning) into stablecoins
Lock in value without withdrawing funds
Prepare for local spending, airtime, bill payments, or off-ramps
This swap flow is a core part of building any crypto-native experience that wants to bridge volatility and stability.
