> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Swap bitcoin to USDT

> A BTC to USDT swap end to end, from balance check through to the confirmed stablecoin balance.

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](https://www.bitnob.dev/api-reference/balances/list-balances.md), or [Get Balance By Currency](https://www.bitnob.dev/api-reference/balances/get-balance-by-currency.md) for a single asset.

```bash theme={null}
GET /api/balances/BTC
```

If you're listing balances across every currency:

```bash theme={null}
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](https://www.bitnob.dev/api-reference/trading/create-quote.md). This allows you to show the user what they’ll receive.

```bash theme={null}
POST /api/trading/quotes
```

**Example request:**

```json theme={null}
{
    "base_currency": "BTC",
    "quote_currency": "USDT",
    "quantity": "0.0001",
    "side": "sell"
}
```

**Example response:**

```json theme={null}
{
    "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](https://www.bitnob.dev/api-reference/trading/submit-order.md), and [Get Order By ID](https://www.bitnob.dev/api-reference/trading/get-order-by-id-or-reference.md) to confirm it settled.

```bash theme={null}
POST /api/trading/orders
```

**Example request:**

```bash theme={null}
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:**

```json theme={null}
{
    "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:

```bash theme={null}
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.

## Next

> [card] [Track orders and history](https://www.bitnob.dev/docs/trading/trade-status-and-history.md)
>
> Confirm and reconcile the swap.

> [card] [Handle trading failures](https://www.bitnob.dev/docs/trading/error-handling-patterns.md)
>
> Before you take this to production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.