EigenWallet Documentation

Introduction

EigenWallet is a self-custodial desktop wallet for Bitcoin (BTC) and Monero (XMR) with a built-in peer-to-peer exchange powered by atomic swaps. It is designed for users who want full sovereignty over their funds, strong network-level privacy, and the ability to convert between BTC and XMR without ever handing custody to a third party.

This documentation walks you from first install all the way to advanced topics such as running a maker node, configuring custom Tor circuits, and integrating hardware wallets. Sections are self-contained, so you can use the sidebar on the left to jump to whatever you need.

What is EigenWallet

EigenWallet (formerly UnstoppableSwap) is an open-source desktop application that combines three things into one cohesive interface:

• A non-custodial wallet for Bitcoin and Monero. Private keys are generated locally and never leave your device.
• An atomic swap engine that exchanges BTC for XMR (and vice versa) directly between peers, with cryptographic guarantees against counterparty fraud.
• A privacy layer that routes all coordination and chain queries through Tor by default.

Unlike a centralized exchange, EigenWallet has no accounts, no KYC, no order books held by a company, and no possibility of frozen funds. The only counterparties are the network and the peer you are swapping with — and neither needs to be trusted.

System Requirements

Operating systems

• Windows 10 or later (64-bit)
• macOS 12 Monterey or later (Intel & Apple Silicon)
• Linux: any glibc 2.31+ distribution (Ubuntu 20.04+, Fedora 36+, Arch, etc.)

Hardware

• Dual-core 64-bit CPU
• 4 GB RAM minimum, 8 GB recommended
• 2 GB free disk space (more if running a full Monero node)
• Stable internet connection capable of sustained Tor traffic

Installation

Always download EigenWallet from the official website or the project's GitHub releases page. Verify the signature of the downloaded artifact before running it.

Windows

1. Download the EigenWallet-Setup-x.y.z.exe installer.
2. Right-click the file and choose Properties → Unblock.
3. Run the installer and follow the on-screen instructions.

macOS

1. Download the EigenWallet-x.y.z.dmg image.
2. Open the image and drag EigenWallet into your Applications folder.
3. On first launch, right-click the app and choose Open to bypass Gatekeeper for unsigned builds.

Linux

# AppImage
chmod +x EigenWallet-x.y.z.AppImage
./EigenWallet-x.y.z.AppImage

# Debian / Ubuntu
sudo dpkg -i eigenwallet_x.y.z_amd64.deb

# Fedora
sudo rpm -i eigenwallet-x.y.z.x86_64.rpm

First Launch

On first launch EigenWallet performs a brief environment check: Tor connectivity, write access to the application data directory, and clock skew. If any check fails, you will be guided through a fix before continuing.

You will then be presented with two choices: Create a new wallet or Restore from recovery phrase.

Creating a Wallet

1. Choose Create a new wallet on the welcome screen.
2. Set a strong local password. This encrypts the wallet on disk.
3. EigenWallet generates a 24-word BIP39 recovery phrase.
4. Write the phrase down on paper in the exact order shown.
5. Confirm a random subset of the words to prove you saved them.

Recovery Phrase & Backup

The 24-word recovery phrase is the master backup of your wallet. It deterministically derives every Bitcoin and Monero address, every private key, and every future address you will ever use.

How to store it

• Write it on paper or stamp it into metal. Never store it digitally.
• Keep at least two physical copies in geographically separate, secure locations.
• Never photograph it, type it into a password manager, or share it with anyone.
• EigenWallet support will never ask for your recovery phrase. Anyone who does is an attacker.

Optional passphrase (25th word)

Advanced users can add an optional passphrase that acts as a 25th word. The same 24 words combined with different passphrases derive completely independent wallets. This enables plausible deniability but increases the risk of permanent loss if the passphrase is forgotten.

Restoring a Wallet

1. Launch EigenWallet and choose Restore from recovery phrase.
2. Enter the 24 words in the original order.
3. If you used an optional passphrase, enable the toggle and enter it.
4. Set a new local password for this device.
5. Wait while EigenWallet scans the chains for prior activity. Monero restores may take longer because the scan happens client-side for privacy reasons.

Receiving Bitcoin

Open the Bitcoin tab and click Receive. EigenWallet will generate a fresh, never-before-used native SegWit (bech32) address. Share this address with the sender or display the QR code.

Receiving Monero

Open the Monero tab and click Receive. Monero addresses can safely be reused because of stealth address technology — every incoming transaction goes to a unique, one-time output that only you can spend.

For payment identification you can attach a payment ID or generate an integrated address from the receive screen.

Sending Funds

1. Open the asset tab (Bitcoin or Monero).
2. Click Send and enter the recipient address.
3. Enter the amount, or click Max to send the entire balance.
4. Choose a fee priority: Low, Normal, or High.
5. Review the transaction summary and confirm with your wallet password.

EigenWallet broadcasts the transaction through your configured node, optionally over Tor. The status bar will show confirmations as they accumulate.

Network Fees

Fees are paid to the underlying blockchain network, not to EigenWallet. The wallet provides three preset levels for each asset and shows the estimated confirmation time.

• Bitcoin fees are estimated using a local mempool model and adjust dynamically.
• Monero fees are almost always negligible due to dynamic block size targeting.

Swaps Overview

Atomic swaps let two parties exchange Bitcoin for Monero (or vice versa) without trusting each other and without an intermediary holding either party's funds. EigenWallet implements the Farcaster / COMIT-style cross-chain atomic swap protocol.

Roles

• Taker — initiates a swap against an existing offer. Most regular users are takers.
• Maker — publishes offers and provides liquidity. Makers run an Automated Swap Backend (ASB).

Cryptographic primitives

• Hash-time-locked contracts (HTLCs) on Bitcoin
• Adaptor signatures (Schnorr) for atomicity across chains
• Bulletproofs and ring signatures for Monero privacy

Performing a Swap

1. Open the Swap tab.
2. Choose the direction (BTC → XMR is the most common).
3. Browse the offer list. Offers display rate, liquidity, and maker reputation.
4. Select an offer, enter the amount, and review the quote.
5. Confirm the swap. EigenWallet locks your Bitcoin into the swap contract.
6. Wait for the maker to lock the corresponding Monero.
7. EigenWallet completes the cryptographic exchange automatically; your XMR appears in your Monero balance.

Swap Lifecycle

A swap progresses through clearly defined phases. EigenWallet surfaces each one in the swap timeline:

1. Quote — negotiated price and amounts.
2. BTC Lock — taker funds the Bitcoin HTLC.
3. XMR Lock — maker funds the Monero output.
4. XMR Redeem — taker claims Monero by revealing a secret.
5. BTC Redeem — maker claims Bitcoin using that secret.

Each phase has a time-lock. If a phase does not complete in time, the protocol enters a refund path and both parties keep their original funds.

Refunds & Recovery

Funds in an active swap are never lost. If the counterparty disappears, your machine crashes, or the network goes down, the refund mechanism guarantees recovery:

• Reopen EigenWallet and select the affected swap from the history list.
• Click Resume. The app reconciles state from the chains.
• If the refund time-lock has passed, click Refund to broadcast the recovery transaction.

Tor & Network Privacy

EigenWallet bundles a Tor client and routes all peer communication, offer discovery and chain queries through it by default. Your IP address is never exposed to makers, takers, or public RPC endpoints.

Customizing Tor

• Use the bundled Tor (default) — zero configuration.
• Connect to an external Tor daemon on 127.0.0.1:9050.
• Configure pluggable transports (obfs4, snowflake) for censored networks.

The Tor status indicator in the bottom bar shows the current circuit health. Click it to request a new identity.

Security Best Practices

• Always download EigenWallet from the official source and verify signatures.
• Keep your operating system and EigenWallet up to date.
• Use a strong, unique local password — at least 12 characters with mixed case, digits, and symbols.
• Store your recovery phrase offline, in metal if possible.
• Use a hardware wallet for large balances.
• Never paste your recovery phrase into a website, email, or chat.
• Verify recipient addresses on a second device before sending large amounts.

Hardware Wallet Integration

EigenWallet supports popular hardware wallets for Bitcoin signing: Ledger (Nano S Plus, Nano X, Stax) and Trezor (Model T, Safe 3). Private keys never leave the device; EigenWallet acts only as a watch-only interface and broadcast layer.

1. Connect your hardware wallet via USB and unlock it.
2. In EigenWallet go to Settings → Hardware Wallet.
3. Click Pair and approve the connection on the device screen.
4. Choose a derivation path or accept the default (m/84'/0'/0').

Biometric Unlock

On supported operating systems (Windows Hello, Touch ID, Linux fprint), you can unlock EigenWallet using biometrics instead of typing your local password. The wallet password is stored in the OS secure enclave or keyring and released only after biometric verification.

Biometric unlock is convenience-only — your recovery phrase is still the ultimate authority over your funds.

Threat Model

EigenWallet is designed to protect against the following classes of adversaries:

• Network observers — ISPs, public Wi-Fi operators, passive surveillance.
• Malicious counterparties — takers or makers attempting to steal funds mid-swap.
• Compromised RPC providers — public Bitcoin/Monero nodes attempting to deanonymize users.
• Local data exfiltration — through full-disk encryption and per-wallet password.

It does not protect against a fully compromised operating system, hardware key-loggers, or physical coercion. For those threat models, use a dedicated air-gapped signing device and operational security practices.

EUR On-Ramp (SEPA)

Users in supported EU countries can buy Monero with euros via SEPA bank transfer directly inside EigenWallet. The on-ramp partner handles fiat conversion; resulting XMR is delivered to your self-custodial wallet.

1. Open the Buy tab and choose EUR → XMR.
2. Enter the desired amount and review the quote (the quote is locked for 15 minutes).
3. Initiate the SEPA transfer from your bank using the provided reference code.
4. Once the transfer settles (usually within 1 business day), XMR is sent to your wallet.

Running a Maker Node (ASB)

The Automated Swap Backend (ASB) is a headless daemon that publishes offers and provides liquidity in exchange for fees. Operators typically run it on a VPS or home server.

Requirements

• Linux server, 1 CPU / 1 GB RAM minimum
• Bitcoin and Monero balances to lock as liquidity
• A reachable network endpoint (clearnet or Tor hidden service)

Quick start

# Install
curl -L https://eigenwallet.org/install-asb.sh | bash

# Configure
asb config init
vim ~/.config/eigenwallet/asb/config.toml

# Run
asb start --network mainnet

Configure your fee schedule, minimum and maximum swap amounts, and connected nodes in config.toml. Monitor operations with asb logs and asb balance.

Command Line Interface

Power users can drive EigenWallet from a terminal. The CLI exposes wallet operations, swap execution, and diagnostics.

eigen wallet create --name primary
eigen wallet balance --asset btc
eigen swap quote --from btc --to xmr --amount 0.05
eigen swap execute --offer <id> --amount 0.05
eigen tor status

Run eigen --help for the full command tree. All commands accept --json for machine-readable output.

Advanced Configuration

Configuration lives at ~/.config/eigenwallet/config.toml on Linux/macOS and %APPDATA%\EigenWallet\config.toml on Windows.

[network]
use_tor = true
tor_socks_port = 9050

[bitcoin]
electrum_url = "ssl://electrum.example.org:50002"
target_blocks = 3

[monero]
daemon_url = "http://node.example.org:18081"
restore_height = 3200000

Custom Node Connections

By default EigenWallet connects to a curated set of community nodes over Tor. For maximum sovereignty, point the wallet at your own full node:

• Bitcoin — run bitcoind with an Electrum server (electrs, fulcrum) and configure the Electrum URL.
• Monero — run monerod and point EigenWallet at its RPC port (default 18081).

Troubleshooting

Tor fails to connect

Some networks block Tor. Enable pluggable transports under Settings → Network → Bridges and try obfs4 or snowflake.

Swap stuck in "BTC Lock"

This usually means low Bitcoin fees and slow confirmation. Wait for confirmations or use Settings → Bitcoin → RBF Bump to increase the fee.

Monero balance shows 0 after restore

Monero restore scans the blockchain from a given height. Make sure the restore height predates your first transaction, then allow the scan to finish (the progress bar at the bottom shows ETA).

Application won't start

Launch from a terminal with EIGEN_LOG=debug to see detailed logs. Attach them when filing a bug report.

FAQ

Is EigenWallet free?

Yes. The application is open source and free to use. Network fees and (small) maker fees on swaps still apply.

Do I need to KYC?

No — except for the optional fiat on-ramp, which is operated by a regulated partner.

Can I use EigenWallet on a phone?

EigenWallet is desktop-first. A companion mobile app is on the roadmap.

Which atomic swap protocol is used?

The current implementation is based on the COMIT BTC↔XMR specification using adaptor signatures.

Glossary

• Atomic swap — a trustless cross-chain exchange where either both sides complete or neither does.
• HTLC — Hash-Time-Locked Contract; a script that releases funds based on a hash preimage or a timeout.
• Adaptor signature — a Schnorr signature variant that ties the reveal of a secret to the act of signing.
• Maker / Taker — liquidity provider and consumer respectively, in a peer-to-peer market.
• Stealth address — Monero's one-time output address derived per transaction for unlinkability.
• SegWit (bech32) — modern Bitcoin address format with lower fees and better error detection.

Contributing

EigenWallet is community-driven. Contributions of code, documentation, translations, and bug reports are welcome.

1. Fork the repository on GitHub.
2. Create a feature branch and open a pull request against main.
3. Sign your commits and include test coverage for new functionality.
4. Discuss large changes in an issue first.

Changelog

v1.0.0

• Rebrand from UnstoppableSwap to EigenWallet.
• New unified wallet interface for Bitcoin and Monero.
• Hardware wallet integration (Ledger, Trezor).
• Tor pluggable transports in the GUI.

v0.13

• SEPA on-ramp for EUR → XMR.
• Improved swap recovery UX.

v0.12

• Adaptor signature implementation upgrade.
• New offer discovery protocol with reduced metadata leakage.