Swap bitcoin to USDT

This tutorial shows you how to convert Bitcoin (BTC) from a user’s Bitnob wallet into USDT 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

Key concepts

Swaps allow users to convert volatile assets (BTC) into stable assets (USDT) 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 and USDT 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 with Get Balances, or Get Balance By Currency for a single asset.

GET /api/balances/BTC

If you’re listing balances across every currency:

GET /api/balances

From the response, look for the wallet with “currency”: “BTC” and check available_balance.

Step 2: Get a swap quote (optional)

You can fetch a live rate before executing the swap with Quotes. This allows you to show the user what they’ll receive.

POST /api/trading/quotes

Example request:

{
    "base_currency": "BTC",
    "quote_currency": "USDT",
    "quantity": "0.0001",
    "side": "sell"
}

Example response:

{
    "success": true,
    "message": "Quote retrieved successfully",
    "data": {
        "quote": {
            "id": "b8da95f6-13b6-41f3-9675-9d24535df1b3",
            "base_currency": "BTC",
            "quote_currency": "USDT",
            "side": "SELL",
            "quantity": "0.0001",
            "price": "88989.119625",
            "expires_at": "2026-03-22T13:10:46.771686117Z",
            "created_at": "2026-03-22T13:10:16.771686367Z",
            "original_quantity": "0.0001",
            "consumed_quantity": "0",
            "remaining_quantity": "0.0001",
            "exchange": {
                "send_quantity": "0.00010000",
                "send_currency": "BTC",
                "receive_quantity": "8.89",
                "receive_currency": "USDT"
            }
        }
    },
    "metadata": {
        "request_id": "trading_req_019d15aa-ecb4-7d55-90a1-16784f39c5a5"
    },
    "timestamp": "2026-03-22T13:10:16.790192295Z"
}

The quote expires fast, so read the window from expires_at. You should show this info to the user (rate, amount they’ll receive) before confirming the swap.

Step 3: Execute the quote

To perform the conversion, send a swap request: see Create Order, and Get Order By ID to confirm it settled.

POST /api/trading/orders

Example request:

curl --location 'https://api.bitnob.com/api/trading/orders' \
--header 'Content-Type: application/json' \
--header 'x-auth-client: CLIENT_ID' \
--header 'x-auth-timestamp: TIMESTAMP' \
--header 'x-auth-nonce: NONCE' \
--header 'x-auth-signature: SIGNATURE' \
--data '{
    "base_currency": "BTC",
    "quote_currency": "USDT",
    "side": "sell",
    "quantity": "0.0001",
    "price": "88989.119625",
    "quote_id": "b8da95f6-13b6-41f3-9675-9d24535df1b3",
    "reference": "user-btc-sell"
}'

Example response:

{
    "success": true,
    "message": "Order submitted successfully",
    "data": {
        "order": {
            "id": "ae56c2eb-74a4-40c6-bb5f-acda2d0e55bb",
            "base_currency": "BTC",
            "quote_currency": "USDT",
            "side": "SELL",
            "order_type": "limit",
            "quantity": "0.0001",
            "price": "88989.119625",
            "status": "filled",
            "created_at": "2026-03-22T13:15:20.595989775Z",
            "updated_at": "2026-03-22T13:15:20.595989775Z",
            "filled_quantity": "0.0001",
            "remaining_quantity": "0",
            "quote_id": "b8da95f6-13b6-41f3-9675-9d24535df1b3",
            "reference": "user-btc-sell"
        },
        "fills": [
            {
                "id": "19ffd357-f494-400a-b609-0f7904934ec2",
                "order_id": "ae56c2eb-74a4-40c6-bb5f-acda2d0e55bb",
                "quantity": "0.0001",
                "created_at": "2026-03-22T13:15:21.621546159Z"
            }
        ],
        "quote_consumption": {
            "quote_id": "b8da95f6-13b6-41f3-9675-9d24535df1b3",
            "consumed_quantity": "0.0001",
            "remaining_quantity": "0",
            "is_exhausted": true
        }
    },
    "metadata": {
        "request_id": "trading_req_019d15af-8f82-766e-85ad-50216f8de0ce"
    },
    "timestamp": "2026-03-22T13:15:21.648920462Z"
}

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:

GET /api/balances/USDT

Based on the currency you swapped into. The response includes available_balance, pending_balance, total_balance, and currency.

Handling errors

If the user has insufficient BTC, you’ll get a 422 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 order id 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, 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.

Track orders and history

Confirm and reconcile the swap.

Handle trading failures

Before you take this to production.

Get started

Bitcoin

Stablecoins

Trading

Payouts

Card issuing

Virtual accounts

Swap bitcoin to USDT

Key concepts

Prerequisites

Step 1: Check BTC wallet balance

Step 2: Get a swap quote (optional)

Step 3: Execute the quote

Step 4: Confirm stablecoin wallet balance

Handling errors

Best practices

Summary

Next

Track orders and history

Handle trading failures

​Key concepts

​Prerequisites

​Step 1: Check BTC wallet balance

​Step 2: Get a swap quote (optional)

​Step 3: Execute the quote

​Step 4: Confirm stablecoin wallet balance

​Handling errors

​Best practices

​Summary

​Next

Track orders and history

Handle trading failures

Key concepts

Prerequisites

Step 1: Check BTC wallet balance

Step 2: Get a swap quote (optional)

Step 3: Execute the quote

Step 4: Confirm stablecoin wallet balance

Handling errors

Best practices

Summary

Next