Monero Atomic Swaps CLI: Step-by-Step BTC↔XMR Swap Tutorial

What Are Monero Atomic Swaps?

Atomic swaps are a trustless method for exchanging one cryptocurrency for another without relying on a centralized exchange or intermediary. The word "atomic" refers to the fact that the swap either completes entirely or not at all. There is no possibility of one party receiving funds while the other does not. For Monero users, atomic swaps represent the most decentralized way to exchange BTC for XMR or vice versa, without providing any personal information to a third party.

The BTC-XMR atomic swap protocol was developed by the COMIT Network team and has been available as a command-line tool since 2021. While it requires some technical comfort, the process is straightforward once you understand the steps. This tutorial walks you through every stage of performing a CLI atomic swap, from installation to completion.

Prerequisites

Before you begin, ensure you have the following:

• A computer running Linux, macOS, or Windows (Linux is recommended for best compatibility)
• A Bitcoin wallet with the BTC you want to swap (if selling BTC) or an address to receive BTC (if buying BTC)
• A Monero wallet with an address to receive XMR (if buying XMR) or the XMR you want to swap (if selling XMR). The standard Monero GUI or CLI wallet works
• monero-wallet-rpc — The Monero wallet RPC server, which the swap tool uses to interact with your Monero wallet
• Stable internet connection — The swap process requires ongoing communication with the Bitcoin and Monero networks and may take 30 minutes to several hours
• Patience — Atomic swaps involve multiple on-chain transactions with confirmation requirements, so they are not instant

Installing the Swap CLI Tool

The primary BTC-XMR atomic swap tool is maintained by the COMIT Network. Here is how to install it:

Step 1: Download the Binary

Visit the official releases page on GitHub for the swap tool. Download the appropriate binary for your operating system. For Linux, this is typically a tar.gz archive containing the swap executable. For macOS, look for the darwin build. Extract the archive to a directory in your PATH or a working directory of your choice.

Step 2: Verify the Download

Always verify the cryptographic signature or checksum of downloaded software, especially for tools that handle cryptocurrency. The release page includes SHA256 checksums that you should verify against your downloaded file. On Linux or macOS, use the sha256sum command to compute the hash of your downloaded file and compare it with the published checksum.

Step 3: Set Up monero-wallet-rpc

The swap tool communicates with your Monero wallet through monero-wallet-rpc. Download monero-wallet-rpc from the official Monero downloads page (getmonero.org). Start it with your wallet file:

You will need to specify the daemon address (your Monero node or a remote node), the wallet file path, the RPC bind port (default 18083), and whether to disable RPC authentication for local use. The swap CLI will connect to this RPC server to manage the Monero side of the swap.

Step 4: Verify Installation

Run the swap CLI with the help flag to verify it is working correctly. You should see a list of available commands including options for buying XMR, selling XMR, listing ongoing swaps, and resuming interrupted swaps.

Finding a Swap Provider

Atomic swaps require a counterparty. The swap CLI uses a rendezvous protocol to discover available swap providers (also called makers or automated swap backends, ASBs) on the network.

Understanding the Rendezvous System

Swap providers register themselves on rendezvous points, which are discovery servers that help buyers and sellers find each other. The swap CLI comes preconfigured with default rendezvous points. When you initiate a swap, the tool queries these points to find providers who are currently offering the exchange pair you want.

Listing Available Providers

Use the list-sellers command to see available swap providers. The output shows each provider's peer ID, the exchange rate they are offering, their minimum and maximum swap amounts, and their current availability. Compare rates between providers to get the best deal, and verify that the amount you want to swap falls within their specified range.

Evaluating Providers

When choosing a provider, consider the exchange rate offered (compare with the current market rate), the provider's uptime and reliability reputation within the community, the minimum and maximum swap amounts, and the provider's connection quality. Some community resources maintain lists of known reliable providers, though the trustless nature of atomic swaps means you do not need to trust the provider with your funds.

Executing a BTC to XMR Swap

The most common swap direction is buying XMR with BTC. Here is the step-by-step process:

Step 1: Initiate the Swap

Run the buy-xmr command, specifying the provider's address and the amount of BTC you want to swap. The CLI will connect to the provider and begin the swap negotiation. The tool displays the exchange rate, the amount of XMR you will receive, and asks for confirmation before proceeding.

Step 2: Fund the Bitcoin Lock Transaction

After confirming, the swap tool generates a Bitcoin lock transaction that you need to fund. It displays a Bitcoin address and the exact amount to send. Send the specified BTC amount from your Bitcoin wallet to this address. The swap tool monitors the Bitcoin network for your transaction and waits for the required number of confirmations.

Step 3: Wait for the Protocol to Complete

Once your Bitcoin lock transaction confirms, the protocol proceeds automatically through several phases. The provider locks their XMR in a corresponding Monero lock transaction. Both parties exchange cryptographic proofs. The XMR is released to your Monero wallet. The BTC is released to the provider.

During this process, the CLI displays status updates showing which phase the swap is in. The entire process typically takes 30 minutes to 2 hours, depending on Bitcoin confirmation times and network conditions.

Step 4: Verify Completion

When the swap completes successfully, the CLI confirms that XMR has been transferred to your Monero wallet. Verify the receipt in your Monero wallet by checking recent transactions. The XMR will require 10 confirmations before it is spendable.

Monitoring Swap Progress

The swap CLI provides several commands for monitoring ongoing and past swaps. The history command shows all swaps you have initiated, including their current status and swap IDs. The resume command allows you to continue a swap that was interrupted, which is critical for recovering funds if your connection drops during the process.

Each swap is assigned a unique swap ID that you should record. This ID is essential for resuming interrupted swaps and troubleshooting issues. The tool stores swap state in a local database, so as long as you do not delete this database, you can always resume an incomplete swap.

Handling Edge Cases: Refund Timelocks

The atomic swap protocol includes timelocks that protect both parties from the other failing to complete their part of the swap. Understanding these timelocks is critical for safely participating in atomic swaps.

How Timelocks Work

The Bitcoin lock transaction includes a timelock that allows the buyer (you) to reclaim their BTC if the swap does not complete within a specified period. The typical timelock for BTC-XMR atomic swaps is 72 Bitcoin blocks (approximately 12 hours) for the first checkpoint and 144 blocks (approximately 24 hours) for the final refund window.

If the swap provider goes offline or fails to complete their side, the protocol eventually reaches the timelock expiry. At this point, the swap CLI automatically executes the refund transaction, returning your BTC to your wallet. You do not need to take manual action as long as the swap tool is running.

Critical Rule: Keep the Tool Running

The most important rule for atomic swaps is to keep the swap CLI running until the swap completes or the refund is processed. If you close the tool during an active swap, you risk missing the refund window and potentially losing funds. If you must close the tool, use the resume command as soon as possible to restart the swap monitoring.

Fees and Timing Expectations

Atomic swaps involve several types of fees that you should account for:

• Bitcoin transaction fees — The lock transaction and claim transaction each require Bitcoin fees, which vary based on network congestion
• Monero transaction fees — The Monero lock and claim transactions incur standard Monero network fees, which are typically very low
• Exchange rate spread — Providers typically offer a rate slightly worse than the market rate, with spreads ranging from 1 to 5 percent
• No platform fees — Unlike centralized exchanges, there are no additional platform or service fees

Total time from initiation to completion ranges from 30 minutes (best case, fast Bitcoin confirmations) to several hours (worst case, congested Bitcoin network). Plan accordingly and do not initiate a swap if you need the funds urgently.

Security Considerations

While atomic swaps are trustless at the protocol level, there are operational security considerations to keep in mind:

• Run Tor — The swap CLI communicates over the internet, potentially revealing your IP address. Route connections through Tor for privacy
• Verify software — Only download the swap CLI from official sources and verify checksums. Malicious versions could steal funds
• Backup swap state — The local swap database contains critical information for refunds. Ensure it is backed up
• Monitor the process — Do not leave a swap unattended for extended periods. Check the status periodically
• Start small — If this is your first atomic swap, start with a small amount to familiarize yourself with the process before swapping larger values

CLI Swaps vs Using MoneroSwapper

Atomic swaps via the CLI and using a service like MoneroSwapper serve similar goals (exchanging BTC for XMR without KYC) but offer different trade-offs:

CLI atomic swaps are fully trustless, require no account or intermediary, and represent the most decentralized exchange method. However, they require technical knowledge, command-line comfort, longer waiting times, and vigilant monitoring of the swap process.

MoneroSwapper provides a user-friendly web interface, faster execution, support for multiple cryptocurrency pairs beyond just BTC-XMR, and a streamlined process that requires no technical setup. The trade-off is that you interact with a service rather than swapping directly peer-to-peer.

For technically inclined users who prioritize maximum decentralization and do not mind the complexity, CLI atomic swaps are an excellent option. For users who want a quick, simple, and reliable exchange experience, MoneroSwapper offers a faster path to obtaining XMR without sacrificing the no-KYC principle.

Conclusion

BTC-XMR atomic swaps represent a milestone in decentralized cryptocurrency exchange. The ability to swap Bitcoin for Monero without trusting any intermediary is a powerful tool for financial privacy. While the CLI tool requires more technical effort than using a web-based service, the trustless nature of the protocol provides the strongest possible guarantee that your swap will complete fairly.

As the atomic swap ecosystem matures, with more providers offering liquidity and tools becoming more user-friendly, this technology will become increasingly accessible. For now, the CLI tool is a capable and reliable method for anyone willing to invest the time to learn it. Combined with services like MoneroSwapper for quicker exchanges, Monero users have a robust set of options for acquiring and using XMR privately.