Quick Start Guide

📘 About This Guide

This guide uses Ethereum as an example blockchain. xBTC supports multiple blockchains including Ethereum, Solana, BSC, Arbitrum, Base, and others. The basic process is similar across all supported chains, but you'll need to use the appropriate wallet for your chosen blockchain (e.g., Phantom for Solana, MetaMask for EVM chains).

This guide will walk you through the process of trading wrapped BTC for native Bitcoin on xBTC. Whether you want to sell wrapped BTC for native BTC or buy wrapped BTC with native BTC, this guide covers everything you need to get started.

1
Connect Wallets
→
2
Create/Find Order
→
3
Send BTC
→
4
Complete Order

1. Prerequisites

1.1 Required Wallets

You will need two wallets to use xBTC:

Blockchain Wallet (e.g., MetaMask for Ethereum)

Used for interacting with the smart contract on your chosen blockchain. Required for creating orders, approving wrapped BTC, and completing transactions.

  • Ethereum/EVM chains: MetaMask (metamask.io)
  • Solana: Phantom (phantom.app)
  • Configure the appropriate network for your chosen blockchain

Unisat (Bitcoin Wallet)

Used for sending and receiving Bitcoin transactions. Required for buying orders and receiving BTC payments.

  • Download from unisat.io
  • Create or import a wallet
  • Ensure you're on the correct Bitcoin network (Mainnet or Testnet)

1.2 Supported Address Types

xBTC supports the following Bitcoin address formats:

Important

Legacy addresses (starting with 1, 3, m, or n) are not supported. Please use SegWit or Taproot addresses.

2. Connecting Your Wallets

1 Connect MetaMask
  1. Click the "Connect MetaMask" button in the top navigation bar
  2. A MetaMask popup will appear requesting connection permission
  3. Select the account you want to use and click "Connect"
  4. Once connected, the button will display your shortened address
2 Connect Unisat
  1. Click the "Connect Unisat" button next to MetaMask
  2. Unisat wallet popup will request connection permission
  3. Approve the connection request
  4. Your Bitcoin address will be displayed once connected

Tip

Both wallets need to be connected for full functionality. You can check connection status in the navigation bar.

3. Creating a Sell Order

To sell your wrapped BTC for native Bitcoin:

1 Open Create Order Form

Click the "Create Order" button on the main page to open the order creation form.

2 Fill in Order Details
3 Approve and Create
  1. Click "Create Order"
  2. If needed, approve the wrapped BTC spending in your wallet (MetaMask for Ethereum)
  3. Confirm the create order transaction in your wallet
  4. Wait for the transaction to be confirmed

Order Created!

Your order is now active and visible in the order book. Buyers can see your order and purchase wrapped BTC by sending native BTC to your address.

4. Buying an Order

To buy wrapped BTC with native Bitcoin:

1 Find an Order

Browse the order book on the main page. Active orders show:

2 Click Buy

Click the "Buy" button on the order you want to purchase. This opens the buy order modal.

3 Enter Purchase Amount

Partial Fills

You can partially fill an order by sending less than the full BTC amount. You'll receive wrapped BTC proportional to the native BTC you send.

4 Build and Sign Transaction
  1. Click "Build Transaction"
  2. The system will create a Bitcoin transaction with:
    • Payment to the seller's BTC address
    • An OP_RETURN output containing the order ID and your receiving address
  3. Sign the transaction in your Unisat wallet
  4. The transaction will be broadcast to the Bitcoin network

OP_RETURN Data

The OP_RETURN output is critical! It contains your order ID and receiving address, which allows the smart contract to verify your purchase and send wrapped BTC to the correct address.

5. Completing an Order

After the BTC transaction is confirmed:

1 Wait for Confirmations

The Bitcoin transaction needs a minimum number of confirmations (typically 3-6) before the order can be completed. You can check the confirmation status in the order details.

2 Complete the Order
  1. Once sufficient confirmations are reached, click "Complete" on the order
  2. The system will verify:
    • Block header validity
    • Merkle proof of transaction inclusion
    • Transaction outputs (payment and OP_RETURN)
  3. Confirm the complete order transaction in your wallet (e.g., MetaMask for Ethereum)
  4. Wrapped BTC will be transferred to the buyer's address

Order Completed!

Congratulations! The wrapped BTC has been transferred to the buyer, and the seller has received native BTC. The transaction is now complete.

6. Cancelling an Order

If you created an order and want to cancel it:

1 Request Cancellation
  1. Go to "My Orders" (requires wallet connection)
  2. Find your active order and click "Request Cancel"
  3. Confirm the transaction in your wallet
2 Wait for Waiting Period

There is a mandatory waiting period (typically 15 minutes) after requesting cancellation. This prevents front-running attacks where a seller cancels after seeing an incoming BTC transaction.

3 Execute Cancellation
  1. After the waiting period, click "Execute Cancel"
  2. Confirm the transaction in your wallet
  3. Your wrapped BTC will be returned to your wallet

Warning

If someone sends BTC to your order during the waiting period, the order may be completed instead of cancelled. Only request cancellation if you're sure no one is about to buy your order.

7. Order Status Reference

Status Description
Active Order is available for purchase. Wrapped BTC is locked in the smart contract.
Completed Order has been fully filled. All wrapped BTC has been transferred to the buyer(s).
Cancelled Order was cancelled by the seller. Wrapped BTC has been returned.

8. Troubleshooting

MetaMask Connection Failed

Unisat Connection Failed

Transaction Pending Too Long

Order Completion Failed

Need More Help?

Check out the FAQ for common questions, or refer to the BTC Verification documentation for technical details about how transactions are validated.