Agentic AQUA
Agentic AQUA is an MCP server and CLI for managing Bitcoin, Liquid, and Lightning wallets, plus swaps, fiat payouts, and JAN3 account operations.
Generate/import/export/delete Bitcoin and Liquid wallets from one BIP39 seed, with watch-only descriptor support.
Check unified BTC/Liquid balances, generate receive addresses/QRs, view transactions, and check tx status.
Send BTC, L-BTC, and Liquid assets (e.g., USDt); sweep entire balances; set fee rates.
Pay/receive Lightning invoices or Lightning Addresses via Indra/Boltz, decode invoices, check swap status, and refund failed sends.
Swap/peg BTC ↔ L-BTC and Liquid/cross-chain assets via SideSwap, SideShift, and Changelly.
Pay Argentine bank accounts in ARS via WapuPay funded by USDT or L-BTC.
Login to JAN3, manage sessions, enable/rebind Lightning Address, and check/buy Lightning usernames.
Generate/decode QR codes and diagnose/repair config.
Provides tools for managing Bitcoin wallets, including generating addresses, checking balances, sending transactions, and importing/exporting descriptors.
Provides tools for sending and receiving payments via the Lightning Network using L-BTC, including generating invoices and paying invoices through Boltz swaps.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Agentic AQUA Show my Bitcoin and Liquid balances"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Agentic AQUA
MCP server and CLI for managing Bitcoin and Liquid Network wallets through AI assistants like Claude. One seed backs both networks (unified wallet). Agentic AQUA can also operate on the Lightning Network.
Features
Generate & Import - Create new wallets or import existing seeds
Unified Wallet - One seed (mnemonic) for Bitcoin and Liquid;
unified_balanceshows bothBitcoin (onchain) - BIP84 wallets, balance and send via
btc_*tools (BDK)Watch-Only - Import CT descriptors for balance monitoring
Send & Receive - Full transaction support (L-BTC, BTC, and Liquid assets like USDt)
Lightning - Send and receive via Lightning using L-BTC
Assets - Native support for L-BTC, USDt, and all Liquid assets
Swaps & Pegs - Convert BTC ↔ L-BTC and swap Liquid/cross-chain assets via SideSwap, SideShift, and Changelly
JAN3 Account - Login, Lightning Address, and WapuPay (pay ARS bank accounts with USDT or L-BTC) via your JAN3 account
Secure - Encrypted storage, no remote servers for keys
Related MCP server: lightning-mcp
Installation
Quickest way: just ask your AI agent directly:
Install this MCP server: https://pypi.org/project/agentic-aqua/
Python 3.13 required.
Recommended (uv tool install)
If you don't have uv installed:
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"Install Agentic AQUA:
uv tool install --python 3.13 agentic-aquaThis creates a permanent agentic-aqua executable. Find its full path with:
which agentic-aqua
# Example: /Users/yourname/.local/bin/agentic-aquaConfigure Claude Desktop (~/.claude/claude_desktop_config.json) using that path:
{
"mcpServers": {
"agentic-aqua": {
"command": "/full/path/to/agentic-aqua",
"args": []
}
}
}Restart Claude Desktop and you're ready to use Bitcoin and Liquid wallets.
Updating / removing:
uv tool upgrade agentic-aquato update,uv tool uninstall agentic-aquato remove.
For Developers
Clone and install from source:
git clone https://github.com/jan3dev/agentic-aqua.git
cd agentic-aqua
uv python install 3.13
uv sync --python 3.13Configure Claude Desktop using the full path to uv (find with which uv):
{
"mcpServers": {
"agentic-aqua": {
"command": "/full/path/to/uv",
"args": ["run", "--python", "3.13", "--directory", "/absolute/path/to/agentic-aqua", "python", "-m", "aqua.server"]
}
}
}Quick Start
Once connected, you can ask Claude to:
"Create a new wallet" (creates both Bitcoin and Liquid wallets from one seed)
"Show my balance" / "What's my Bitcoin balance?"
"Generate a receive address" (Liquid or Bitcoin)
"Send 10,000 Sats to bc1..." / "Send 0.001 L-BTC to lq1..."
"Pay this Lightning invoice: lnbc..."
"Receive 50,000 Sats via Lightning"
"Delete my wallet"
Available Tools
Wallet Management
Tool | Description |
| Generate new BIP39 seed |
| Import wallet from seed (also creates Bitcoin wallet) |
| Import watch-only Liquid wallet from CT descriptor |
| Export Liquid CT descriptor for watch-only use |
| Import watch-only Bitcoin wallet from BIP84 descriptor |
| Export Bitcoin BIP84 descriptors + xpub |
| List all wallets |
| Delete a wallet and all its cached data |
⚠️ Bitcoin and Liquid descriptors cannot be derived from each other (different BIP84 paths + Liquid's SLIP-77 blinding key). To watch a unified wallet, import both descriptors separately.
Liquid (lw_*)
Tool | Description |
| Get wallet balances (all assets) |
| Generate Liquid receive address (lq1...) |
| Send L-BTC |
| Send any Liquid asset (USDt, etc.) |
| Sweep the entire L-BTC (or one asset) balance to one address |
| List known Liquid assets (asset_id, ticker, name, precision) |
| Transaction history |
| Get transaction status (txid or explorer URL) |
Bitcoin (btc_*)
Tool | Description |
| Get Bitcoin balance (sats) |
| Generate Bitcoin receive address (bc1...) |
| Bitcoin transaction history |
| Send BTC |
| Sweep the entire Bitcoin balance to one address |
Unified
Tool | Description |
| Get balance for both Bitcoin and Liquid |
Lightning
Tool | Description |
| Pay a Lightning invoice or Lightning Address using L-BTC (~0.1% + ~21 Sats) |
| Check status of a Lightning swap (send or receive) |
| Recover the L-BTC locked up by a failed send swap |
| Decode a BOLT11 invoice without paying it |
| Generate a Lightning invoice to receive L-BTC — disabled by default |
Sends go through Indra, AQUA's Boltz-compatible swap
service (1,000–100,000 Sats, mainnet only). Set "lightning_provider": "boltz" in
~/.aqua/config.json — or AQUA_LIGHTNING_PROVIDER=boltz — to use Boltz instead
(100–25,000,000 Sats, and the only option on testnet). Receiving over Lightning
ships off; re-enable it with "lightning_receive": true. See
docs/CONFIG.md.
When a send fails, its L-BTC stays locked on chain until it is refunded:
lightning_refund (CLI aqua lightning refund --swap-id <id>) recovers it,
cooperatively with the provider where possible and on its own after the swap's
timeout block. See docs/submarine-swap-ln-refund.md.
Swaps — SideSwap (sideswap_*) — BTC ↔ L-BTC pegs and atomic Liquid asset swaps
Tool | Description |
| Live fees, peg minimums, hot-wallet balance |
| Recommend a peg vs an instant swap for a BTC ↔ L-BTC conversion |
| Quote the receive amount for a peg at current fees |
| Peg BTC → L-BTC |
| Peg L-BTC → BTC |
| Check status of a peg order |
| List Liquid assets SideSwap supports for atomic swaps |
| Read-only price quote for a Liquid asset swap |
| Execute an atomic Liquid asset swap (L-BTC ↔ USDt, etc.) |
| Check status of an atomic asset swap |
Swaps — SideShift (sideshift_*) — custodial cross-chain swaps (USDt across chains, BTC ↔ USDt-on-X)
Tool | Description |
| List supported coins and networks |
| Rate / min / max for a pair |
| Fixed-rate quote (~15 min TTL) |
| Recommend SideSwap vs SideShift for a pair |
| Send funds from the wallet via a fixed-rate shift |
| Receive into the wallet via a variable-rate shift |
| Check status of a shift order |
Swaps — Changelly (changelly_*) — USDt-Liquid ↔ USDt on Ethereum/Tron/BSC/Solana/Polygon
Tool | Description |
| List currencies Changelly supports |
| Fixed-rate quote for a USDt-Liquid ↔ USDt-on-X swap |
| Send USDt-Liquid out to USDt on another chain |
| Receive USDt-Liquid from USDt on another chain |
| Check status of a swap order |
WapuPay (wapupay_*) — pay Argentine bank accounts in ARS, funded with USDT or L-BTC on Liquid
Tool | Description |
| Current exchange rates (e.g. USDT/ARS); public, no key needed |
| Preview USDT cost, fee, and rate for an ARS payment |
| Create a direct-fiat order (USDT or L-BTC rail); returns a Liquid funding address |
| Re-issue funding instructions for an existing order |
| Check a direct-fiat order's status |
| List locally-tracked orders |
| List WapuPay transactions |
| Get a single transaction by id |
| Monthly spending limit (USDT) for the account/key |
| Provision a WapuPay API key via your JAN3 account |
JAN3 Account (jan3_*) — login, sessions, and Lightning Address for your JAN3 account
Tool | Description |
| Default login flow: email OTP → verify, saves the session |
| Fallback paid captchaless login flow |
| Status/metadata for a persisted session |
| List all persisted sessions |
| Delete a persisted session |
| Account profile + Lightning Address status |
| Enable/disable the Lightning Address |
| Re-bind Lightning Address delivery to a different wallet (destructive) |
| Check if a Lightning username is available |
| Buy/update the Lightning username (on-chain payment) |
Utilities
Tool | Description |
| Generate a PNG QR code for any content (address, invoice, URI) |
| Decode a QR code from an image file |
| Diagnose (and optionally repair) the |
CLI
Agentic AQUA also ships with a Click-based CLI (aqua) for direct, scriptable wallet operations. It exposes the same operations as the MCP tools.
# Discover commands
aqua --help
aqua wallet --help
aqua btc --help
aqua liquid --help
aqua lightning --help
aqua sideswap --help
aqua sideshift --help
aqua changelly --help
aqua wapupay --help
aqua jan3 --help
aqua qr --help
# Wallet management
aqua wallet generate-mnemonic
aqua wallet import-mnemonic --mnemonic-stdin --wallet-name default --network mainnet --password-stdin
aqua wallet list
aqua wallet delete --wallet-name old
# Watch-only descriptors (Bitcoin and Liquid are separate)
aqua btc export-descriptor --wallet-name default
aqua btc import-descriptor --wallet-name cold --descriptor "wpkh([fp/84h/0h/0h]xpub.../0/*)#cs"
aqua liquid export-descriptor --wallet-name default
aqua liquid import-descriptor --wallet-name cold --descriptor "ct(slip77(...),elwpkh(...))"
# Balances
aqua balance # unified (BTC + Liquid)
aqua btc balance --wallet-name default
aqua liquid balance --wallet-name default
# Receive addresses
aqua btc address
aqua liquid address
# Send (--wallet-name is required for on-chain sends)
aqua btc send --wallet-name default --address bc1... --amount 10000
aqua liquid send --wallet-name default --address lq1... --amount 50000
aqua liquid send-asset --wallet-name default --address lq1... --amount 1000000 --asset-id <asset_id>
# (or use --asset-ticker USDt instead of --asset-id)
# Transaction history & status
aqua btc transactions
aqua liquid transactions
aqua liquid tx-status --tx <txid|explorer_url>
# Lightning (L-BTC via Indra / Boltz)
aqua lightning send --invoice lnbc...
aqua lightning send --ln-address user@domain.com --amount-sats 1000
aqua lightning status --swap-id <id>
aqua lightning decode --invoice lnbc...
# Swaps & pegs
aqua sideswap peg-in --wallet-name default # BTC -> L-BTC
aqua sideswap peg-out --amount 50000 --btc-address bc1... --wallet-name default
aqua sideswap swap --asset-ticker USDt --amount 50000 --wallet-name default
aqua sideshift send --deposit-coin btc --deposit-network liquid --settle-coin usdt --settle-network tron \
--settle-address T... --deposit-amount 0.001 --wallet-name default
aqua changelly send --external-network tron --settle-address T... --amount-from 100 --wallet-name default
# WapuPay (pay ARS bank accounts, funded with USDT or L-BTC on Liquid)
aqua wapupay quote --amount-ars 10000 --alias some.alias
aqua wapupay create-order --amount-ars 10000 --alias some.alias --wallet-name default
# then fund the returned address:
aqua liquid send-asset --wallet-name default --address <funding_address> --amount <amount> --asset-ticker USDt
# QR
aqua qr decode ./invoice-qr.png
# Run as MCP stdio server
aqua serve # recommended
aqua-mcp # direct MCP entrypointOutput defaults to a human-readable table on the terminal and JSON when piped. Force a format with --format json or --format pretty.
Loading seeds safely
Avoid pasting seeds into the chat with your agent. Because it will persist in logs and will be sent to the AI provider, agent transcripts may persist them. The recommended workflow is to use this command that hides the text input:
aqua wallet import-mnemonic --mnemonic-stdin --wallet-name defaultx --network mainnet --password-stdinThe CLI honors these variables out of the box:
Variable | Used by |
|
|
|
|
|
|
| Base URL of the Indra swap service (default |
| Any CLI option (Click |
If you would rather pipe secrets from a password manager, every secret-bearing command also accepts --mnemonic-stdin / --password-stdin:
pass show crypto/aqua-mnemonic | aqua-cli wallet import-mnemonic --mnemonic-stdinTips:
Never commit
.envorsecrets.envfiles (the project's.gitignorealready excludes them).Prefer
set -a; . file; set +aoverexport $(cat file)— the former tolerates spaces and quotes inside values.After importing a wallet, the seed is no longer needed for day-to-day operations; only
AQUA_PASSWORDis used to sign transactions.
JAN3 account login
Two login flows, both multi-account (one session per email), ending with a locally saved session:
# Default (free email-OTP)
aqua jan3 login --email you@example.com # emails an OTP
aqua jan3 verify --email you@example.com --otp 123456
# Fallback (paid captchaless), for accounts that can't use the free flow
aqua jan3 login-start --email you@example.com --wallet-name default --password-stdin
aqua jan3 login-complete --email you@example.com --otp 123456Once logged in:
aqua jan3 list-sessions
aqua jan3 user-info --email you@example.com
aqua jan3 logout --email you@example.comConfiguration
Default config location: ~/.aqua/config.json
Migrating from
aqua-mcp? The config dir moved from~/.aqua-mcpto~/.aqua. There is no automatic migration. To carry over your wallets, run once:mv ~/.aqua-mcp ~/.aqua
{
"network": "mainnet",
"default_wallet": "default",
"electrum_url": null,
"auto_sync": true
}Security
Seeds are encrypted at rest using a password (PBKDF2 + Fernet). Without a password, the seed is stored base64-encoded only — use a password for real funds. Note: this password is NOT a BIP39 passphrase; the derived Liquid/Bitcoin keys depend solely on the seed, so the same seed restores identical descriptors in any BIP39-compliant wallet (AQUA, Blockstream App, Jade, etc.).
For maximum security you can:
Generate wallet on an air-gapped device
Export the CT descriptor
Import as watch-only on your daily machine
All private key operations happen locally. Only blockchain sync uses Blockstream's public servers.
Development
# Install with dev dependencies
uv python install 3.13
uv sync --python 3.13 --all-extras
# Run tests
uv run --python 3.13 python -m pytest tests/
# Format code
uv run black src/
uv run ruff check src/Architecture
AI Assistant ←→ MCP Server (Python) ←→ LWK (Liquid) ──→ Electrum/Esplora
│
├──→ BDK (Bitcoin) ──→ Esplora (Blockstream)
│
└──→ Indra / Boltz ──→ LightningCredits
Built with:
Available Tools
73 toolsbtc_addressA
Generate a Bitcoin receive address (bc1...). Also returns qr_code_path: a PNG QR of the address — display it to the user so they can scan it.
Inputs: index, wallet_name.
btc_balanceB
Get Bitcoin wallet balance in Satoshis
Inputs: wallet_name.
btc_export_descriptorA
Export the Bitcoin BIP84 descriptors + xpub for a wallet. ONLY returns Bitcoin — for the Liquid CT descriptor (different derivation path + SLIP-77 blinding key), use lw_export_descriptor.
Inputs: wallet_name.
btc_import_descriptorA
Import a watch-only Bitcoin wallet from a BIP84 descriptor. ONLY imports Bitcoin — to monitor the same seed's Liquid wallet, the user must separately import its CT descriptor with lw_import_descriptor (different derivation path + SLIP-77 key).
Inputs: descriptor (required), wallet_name (required), network, change_descriptor.
btc_sendC
Send BTC to an address
Inputs: amount (required), address (required), wallet_name (required), fee_rate, +1 more.
btc_sweepA
Sweep the entire Bitcoin balance to one address. Fee is deducted from the inputs — leaves 0 sats in the wallet. Use this whenever the user says 'send all', 'sweep', 'drain', 'empty wallet', or 'move everything' on Bitcoin.
Inputs: address (required), wallet_name (required), fee_rate, password.
btc_transactionsA
Get Bitcoin transaction history
Inputs: limit, wallet_name.
changelly_list_currenciesA
List the currencies Changelly supports (Changelly's own asset id format). Useful for discovery; the agentic-aqua surface only enables the curated USDt-Liquid ↔ USDt-on-{ethereum,tron,bsc,solana,polygon} pairs for actual swaps.
Inputs: no named parameters.
changelly_quoteA
Get a fixed-rate Changelly quote for a USDt-Liquid ↔ USDt-on-X swap. Provide exactly one of deposit_amount or settle_amount as a decimal string. Use BEFORE changelly_send to confirm the price with the user.
Inputs: external_network (required), amount_to, direction, amount_from.
changelly_receiveA
Receive USDt-Liquid via a Changelly variable-rate swap. Returns a deposit address on the source chain — the external sender pays to it. Settles to the wallet's Liquid address as USDt-Liquid. STRONGLY RECOMMEND passing external_refund_address. Also returns qr_code_path: a PNG QR of the deposit address — display it to the user so they can scan it.
Inputs: external_network (required), amount_to, amount_from, wallet_name, +1 more.
changelly_sendA
Send USDt-Liquid out via a Changelly fixed-rate swap. Gets a quote, creates the order, and broadcasts the deposit from the local wallet. Refund address is set automatically (the wallet's own Liquid address). ALWAYS call changelly_quote first and confirm the price with the user.
Inputs: settle_address (required), external_network (required), rate_id, password, +3 more.
changelly_statusA
Check the status of a Changelly swap order. Returns is_final / is_success / is_failed booleans. State machine: new → waiting → confirming → exchanging → sending → finished. Failure: failed, refunded, expired, overdue.
Inputs: order_id (required).
delete_walletA
Delete a wallet and all its cached data. IMPORTANT: The agent MUST check balances and ask for user confirmation before calling this tool. Use the 'delete_wallet' prompt for the safe workflow.
Inputs: wallet_name (required).
doctorA
Diagnose (and optionally repair) the AQUA config file (~/.aqua/config.json): reports orphaned/unknown tool keys (the source of the 'Unknown tool in enabled_tools' startup warnings), entries that match the shipped default (prunable to keep the config sparse), and unknown top-level keys (ignored at load until removed). Read-only by default; pass fix=true to apply repairs. Note: the running server reads its tool-gating config once at startup, so any gating change from a fix takes effect on the next server restart.
Inputs: fix.
jan3_enable_lightning_addressA
Enable or disable the user's Lightning Address. Ask the user first: enabling means JAN3/AQUA delivers inbound Lightning payments to their Lightning Address by handing out a batch of Liquid receive addresses this tool registers (received BTC lands on those stored Liquid addresses). On enable, the pool is populated immediately (best-effort, under ln_address_pool). Requires a prior JAN3 login.
Inputs: email (required), enabled (required), wallet_name.
jan3_list_sessionsA
List all persisted JAN3 sessions (metadata only, no tokens).
Inputs: no named parameters.
jan3_ln_check_usernameA
Check whether a Lightning username is free before buying it. Call before jan3_purchase_ln_username to avoid paying for a username that's already taken. Requires an active JAN3 session for the email.
Inputs: email (required), ln_username (required).
jan3_loginA
Default JAN3 login (free, email-OTP): the backend emails a 6-digit OTP to the user's address. Prefer this over the paid captchaless fallback (jan3_login_start). Follow up with jan3_verify.
Inputs: email (required), language.
jan3_login_completeA
Step 2 of the paid captchaless login. Exchanges the OTP for JWT tokens and saves the session to ~/.aqua/jan3/{email}.json (0o600). Only token previews are echoed back — never the full tokens. The result's next_step cues you to offer the user the Lightning Address opt-in (jan3_enable_lightning_address).
Inputs: email (required), otp_code (required), fingerprint.
jan3_login_startA
Fallback JAN3 login (paid captchaless) — use only when the free jan3_login email-OTP flow isn't available for the account. Step 1: crafts a signed L-BTC tx funding AQUA's vault for the CAPTCHALESS_LOGIN price, POSTs it to /api/v2/auth/login/, and the server emails an OTP. Then call jan3_login_complete.
Inputs: email (required), language, password, wallet_name.
jan3_logoutB
Delete a persisted JAN3 session file. Idempotent.
Inputs: email (required).
jan3_purchase_ln_usernameA
Purchase / update the Lightning username for a JAN3 account with an on-chain payment (fund in L-BTC or USDt). TWO-STEP, do NOT pass confirm=true first: (1) call with confirm=false (default) to get a price quote WITHOUT spending — the server locks the price on that order; it returns display_amount (already formatted for the user, e.g. '2000 Sats' for L-BTC or '1.50 USDT' for USDt), amount_base_units (technical), amount, asset_ticker, payment_id and expires_at; SHOW display_amount to the user and get explicit consent; (2) only then call with confirm=true — it funds exactly the quoted order (same payment_id and amount) and errors if the quote expired (re-quote and re-confirm). When telling the user the price, use display_amount verbatim — never surface the raw amount/amount_base_units. Check availability first with jan3_ln_check_username. Requires an active JAN3 session (either flow).
Inputs: email (required), ln_username (required), asset, confirm, +3 more.
jan3_rebind_walletA
Re-bind the account's Lightning Address to a different local wallet (the only path that passes override_fingerprint). DESTRUCTIVE: it moves inbound Lightning delivery to wallet_name and stops delivery to the previously-bound wallet. Use when the account is bound to a wallet you no longer have (new seed, old JAN3 account) or to switch which wallet receives funds. TWO-STEP HANDSHAKE — do NOT pass confirm=true first: (1) call with confirm=false to get a non-mutating preview (ln_username, current_fingerprint->new_fingerprint, warning), SHOW the warning and get explicit user consent; (2) only then call with confirm=true to execute. The ln_username shown is the Lightning Address (a user@domain), it isn't the account login email, never substitute one for the other.already_bound=true means it was a no-op. Requires a prior JAN3 login.
Inputs: email (required), confirm, wallet_name.
jan3_session_infoA
Return non-sensitive info about a persisted JAN3 session (base_url, created_at, captcha_exempt, token previews).
Inputs: email (required).
jan3_user_infoA
Get the AQUA account profile (email, ln_username, fingerprint, feature flags). The ln_username field is the user's full Lightning Address as returned by the backend — surface it verbatim, never append a domain. Carries the LN-address state (ln_address_toggled, new_addresses_needed, fingerprint). When LN-address is active this auto-tops-up the unused-address pool (best-effort, under ln_address_pool). Requires a prior JAN3 login for the email.
Inputs: email (required), wallet_name.
jan3_verifyA
Verify the OTP emailed by jan3_login and persist the JAN3 session for that email (multi-account, 0o600). Ask the user for the 6-digit code from their email. The result's next_step cues you to offer the user the Lightning Address opt-in (jan3_enable_lightning_address).
Inputs: email (required), otp_code (required), fingerprint.
lightning_decodeA
Decode a BOLT11 Lightning invoice without paying it. Returns amount_sats (null for zero-amount invoices), description/message, and expiry_seconds.
Inputs: invoice (required).
lightning_refundA
Recover the L-BTC locked up by a failed Lightning send swap, back to the swap's own wallet (or a given Liquid address). Works with both providers. A cooperative refund is cosigned by the provider and works right away; if the provider declines, the refund branch can be spent on its own once the timeout block passes. claim_public_key and blinding_key only need supplying for swaps created before those fields were stored locally — the error message says when that applies.
Inputs: swap_id (required), address, dry_run, blinding_key, +1 more.
lightning_sendA
Pay a Lightning invoice or Lightning Address using L-BTC from a Liquid wallet (submarine swap). Provider: Indra by default, limits 1,000 – 100,000 Sats; Boltz (lightning_provider="boltz") allows 100 – 25,000,000 Sats. Fees: ~0.1% + miner fees (~21 Sats).
Inputs: invoice (required), password, amount_sats, wallet_name.
lightning_transaction_statusA
Check the status of a Lightning swap (send or receive). For receive: auto-claims L-BTC when settled. For send: queries the provider the swap was created with (returned as provider / provider_status) and retrieves the preimage when claimed.
Inputs: swap_id (required).
lw_addressB
Generate a receive address. Also returns qr_code_path: a PNG QR of the address — display it to the user so they can scan it.
Inputs: index, wallet_name.
lw_balanceA
Get wallet balance for all assets (L-BTC, USDT, etc.)
Inputs: wallet_name.
lw_export_descriptorA
Export the CT descriptor for a wallet (for watch-only import elsewhere)
Inputs: wallet_name.
lw_generate_mnemonicA
Generate a new BIP39 seed phrase for creating a Liquid wallet
Inputs: no named parameters.
lw_import_descriptorB
Import a watch-only wallet from a CT descriptor
Inputs: descriptor (required), wallet_name (required), network.
lw_import_mnemonicA
Import a wallet from a BIP39 seed phrase (creates both Liquid and Bitcoin wallets from the same seed)
Inputs: mnemonic (required), network, password, wallet_name.
lw_list_assetsA
List known Liquid assets (asset_id, ticker, name, precision). Use this to resolve asset IDs for lw_send_asset without a prior balance query.
Inputs: network.
lw_list_walletsB
List all wallets
Inputs: no named parameters.
lw_sendB
Send L-BTC to an address
Inputs: amount (required), address (required), wallet_name (required), password.
lw_send_assetC
Send a Liquid asset (USDT, etc.) to an address
Inputs: amount (required), address (required), asset_id (required), wallet_name (required), +1 more.
lw_sweepA
Sweep the entire L-BTC balance (or full balance of a specific Liquid asset) to one address. Fee is deducted from the inputs — leaves 0 sats of the targeted balance in the wallet. Use this whenever the user says 'send all', 'sweep', 'drain', 'empty wallet', or 'move everything' on Liquid. Asset sweep note: with asset_id set, the asset balance goes to 0 in one tx but L-BTC change may remain because the fee was paid in L-BTC — call lw_sweep again without asset_id to also empty L-BTC.
Inputs: address (required), wallet_name (required), asset_id, password.
lw_transactionsC
Get transaction history
Inputs: limit, wallet_name.
lw_tx_statusA
Get the status of a Liquid transaction. Accepts a txid or a Blockstream explorer URL (e.g. https://blockstream.info/liquid/tx/abc123...)
Inputs: tx (required).
qr_decodeA
Decode a QR code from an image file and return the raw string content. Supports Bitcoin addresses, Liquid addresses, Lightning invoices (BOLT11), and Lightning addresses.
Inputs: image_path (required).
qr_generateB
Generate a PNG QR code for arbitrary content and return qr_code_path. Optionally includes a terminal-friendly block QR string.
Inputs: data (required), filename, terminal, output_dir.
sideshift_list_coinsA
List the coins and networks SideShift supports for cross-chain swaps. Use to discover valid (coin, network) IDs for the other sideshift_* tools.
Inputs: no named parameters.
sideshift_pair_infoA
Get rate, min, and max for a SideShift pair (e.g. USDt-Liquid → USDt-Tron). Returns decimal-string rate / min / max in deposit-coin units.
Inputs: to_coin (required), from_coin (required), to_network (required), from_network (required), +1 more.
sideshift_quoteA
Request a fixed-rate SideShift quote (~15 min TTL). Provide exactly one of deposit_amount or settle_amount as a decimal string. Use BEFORE sideshift_send to confirm the quote with the user.
Inputs: settle_coin (required), deposit_coin (required), settle_network (required), deposit_network (required), +2 more.
sideshift_receiveA
Receive into the local wallet via a SideShift variable-rate shift. Returns a deposit address on the deposit chain — the user (or external sender) sends to it from any wallet. Settle chain MUST be 'bitcoin' or 'liquid'. Both legs must be in the curated allowlist (USDt on ethereum/tron/bsc/solana/polygon/liquid, or BTC on bitcoin) — mirrors AQUA Flutter's supported pairs. Set SIDESHIFT_ALLOW_ALL_NETWORKS=1 to bypass. STRONGLY RECOMMEND passing external_refund_address (the deposit-side sender's address) so a stuck shift can refund automatically. Also returns qr_code_path: a PNG QR of the deposit address — display it to the user so they can scan it.
Inputs: settle_coin (required), deposit_coin (required), settle_network (required), deposit_network (required), +4 more.
sideshift_recommendA
Recommend SideSwap vs SideShift for a cross-asset conversion. SideSwap when both legs are on Bitcoin/Liquid (atomic, lower fees); SideShift when at least one leg is on a non-Liquid chain (custodial, covers 30+ chains).
Inputs: to_coin (required), from_coin (required), to_network (required), from_network (required).
sideshift_sendA
Send funds out via SideShift. Gets a fixed-rate quote, creates the shift, and broadcasts the deposit from the local wallet. Deposit chain MUST be 'bitcoin' or 'liquid'. Both legs must be in the curated allowlist (USDt on ethereum/tron/bsc/solana/polygon/liquid, or BTC on bitcoin) — mirrors AQUA Flutter's supported pairs. Set SIDESHIFT_ALLOW_ALL_NETWORKS=1 to bypass. A refund address is set automatically (the wallet's own deposit-chain address). For non-L-BTC Liquid assets (e.g. USDt-Liquid), the Liquid asset_id is auto-resolved from deposit_coin against the known asset registry — no need to look it up first. Pass liquid_asset_id only to override the registry. ALWAYS call sideshift_quote first and confirm the price with the user.
Inputs: settle_coin (required), deposit_coin (required), settle_address (required), settle_network (required), +9 more.
sideshift_statusA
Check the status of a SideShift shift order. Returns the shift record plus is_final / is_success / is_failed booleans.
Inputs: shift_id (required).
sideswap_execute_swapA
Execute a Liquid atomic swap on SideSwap. Both directions are supported via send_bitcoins: True = L-BTC → asset (default), False = asset → L-BTC. The PSET returned by SideSwap is verified locally against the agreed quote BEFORE signing — the swap is aborted if the wallet's net balance change does not exactly match (refusing to sign protects against a hostile server). The fee tolerance is pinned to L-BTC, so on the asset → L-BTC direction the asset side is checked at strict equality. Order is persisted at every step for crash recovery. ALWAYS call sideswap_quote first and confirm the price with the user before invoking this tool.
Inputs: asset_id (required), send_amount (required), password, wallet_name, +3 more.
sideswap_list_assetsC
List Liquid assets that SideSwap supports for atomic swaps (e.g. L-BTC, USDt, EURx, MEX, DePix).
Inputs: network.
sideswap_peg_inA
Initiate a SideSwap peg-in (BTC → L-BTC). Returns a Bitcoin deposit address; the user (or btc_send) must send BTC to it. After 2 BTC confirmations (~20 min hot path; up to ~17 hours cold path for very large amounts), L-BTC arrives in the Liquid wallet. Recommended over a swap-market trade for amounts ≥ ~0.01 BTC: lower fee (0.1% vs 0.2%) at the cost of waiting. ALWAYS call sideswap_recommend first for large amounts so the user understands the trade-off.
Inputs: password, wallet_name.
sideswap_peg_outB
Initiate a SideSwap peg-out (L-BTC → BTC) and broadcast the L-BTC send. After 2 Liquid confirmations (~2 min) and the federation BTC sweep (typically 15–60 min total), BTC arrives at the user's Bitcoin address. Fees: 0.1% + Bitcoin network fee. Standard way to move L-BTC back to Bitcoin mainchain.
Inputs: amount (required), btc_address (required), wallet_name (required), password.
sideswap_peg_quoteB
Quote the receive amount for a SideSwap peg (BTC ↔ L-BTC) at current fees (0.1% + ~286 sats Liquid claim fee on peg-in). Returns send_amount, recv_amount, fee_amount.
Inputs: amount (required), peg_in, network.
sideswap_peg_statusA
Check the status of a SideSwap peg order (peg-in or peg-out). Returns confirmations progress (X/Y), tx_state, lockup_txid, payout_txid when complete.
Inputs: order_id (required).
sideswap_quoteA
Get a read-only price quote for a SideSwap Liquid asset swap (e.g. L-BTC ↔ USDt). Provide exactly one of send_amount or recv_amount. Use this BEFORE sideswap_execute_swap so the user can confirm the price.
Inputs: asset_id (required), network, recv_amount, send_amount, +1 more.
sideswap_recommendA
Recommend a peg vs an instant swap-market trade for a BTC ↔ L-BTC conversion. Surfaces the trade-off (lower fee but slower) and warns when the amount exceeds SideSwap's hot-wallet liquidity. ALWAYS call this for large conversions before initiating a peg.
Inputs: amount (required), direction (required), network.
sideswap_server_statusA
Fetch SideSwap server status: live fees, minimum amounts, and hot-wallet balances. Call this BEFORE recommending a peg or swap so values reflect current SideSwap state.
Inputs: network.
sideswap_swap_statusA
Get persisted status of a SideSwap atomic asset swap. Once the swap is broadcast, pass the txid to lw_tx_status to track on-chain confirmations.
Inputs: order_id (required).
unified_balanceA
Get balance for both Bitcoin and Liquid networks (unified wallet)
Inputs: wallet_name.
wapupay_create_orderA
Create a WapuPay order and get a Liquid funding address. Funds from USDT (default) or L-BTC — both settle from a Liquid address. Creates the tentative (freezing the quote) and issues funding instructions. Returns address_destination (Liquid), asset_id, funding_amount_usdt, total_amount_usdt, total_funding_amount_base_units (for USDT), total_amount_sats (for LBTC), expires_at and a QR. Pay the TOTAL with lw_send_asset (amount and unit depend on funding_method — follow pay_instructions); WapuPay then makes a P2P payer settle ARS to the bank account. Does NOT broadcast the payment itself — confirm the quote with the user first via wapupay_quote.
Inputs: alias (required), amount_ars (required), type, wallet_name, +3 more.
wapupay_exchange_ratesA
Get WapuPay's current exchange rates (e.g. USDT/ARS). Public — no login or API key.
Inputs: no named parameters.
wapupay_fund_orderA
Issue (or re-issue) Liquid funding instructions for an existing order. Use to recover an order created without funding, or to refresh the funding address before it expires. Returns the funding address + QR.
Inputs: tentative_id (required).
wapupay_ordersA
List locally-tracked WapuPay direct-fiat orders (recovery records on this device), most recent first — distinct from wapupay_transactions (WapuPay's server-side view). Each record carries the orchestrated swap's txids (funding/executed) and status for local tracking.
Inputs: no named parameters.
wapupay_order_statusA
Check a WapuPay P2P order's status (re-read from WapuPay). Returns is_final / is_success / is_failed. States: CREATED → FUNDING_ISSUED → EXECUTED. Terminals: EXPIRED, SETTLED_TO_BALANCE, FAILED.If it contains a funding_transaction_id or executed_transaction_id you can fetch the details with wapupay_transaction if user asks
Inputs: tentative_id (required).
wapupay_provision_accountA
Provision a WapuPay API key via the user's JAN3 account so the other WapuPay tools work. Use when the user wants WapuPay but has no API key set. Requires a prior JAN3 login for the email (either flow: jan3_login then jan3_verify, or jan3_login_start then jan3_login_complete); calls the AQUA backend with that session, then stores the returned key locally (0o600) for all wapupay_* tools — the raw key is never returned, only a masked preview. The AQUA backend issues a fresh key on every call and invalidates the previous one (no grace period), so this only calls the backend when no key is configured yet: if one already exists (env var or stored) it is a no-op (already_configured=true) and never invalidates a working key.
Inputs: email (required).
wapupay_quoteA
Preview the USDT cost, fee, and exchange rate for an ARS payment without creating an order. Call BEFORE wapupay_create_order to confirm the price. Pass alias to validate the bank alias/CBU/CVU (see valid_cbu_alias in the response).
Inputs: amount_ars (required), type, alias.
wapupay_spending_limitA
Get the WapuPay account/key's monthly spending limit (USDT), based on KYC tier.
Inputs: no named parameters.
wapupay_transactionA
Get a single WapuPay transaction by id (UUID or numeric). It can be a funding (crypto), an executed fiat transfer or a refund (crypto) transaction.
Inputs: id (required).
wapupay_transactionsA
List WapuPay transactions (scoped to the WapuPay account/key).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 73 tools
Tools are heavily differentiated by protocol prefix (lw_ for Liquid wallet, btc_ for Bitcoin, sideswap_/sideshift_/changelly_ for swap providers, wapupay_ for fiat, jan3_ for account), which helps. However, there is substantial cross-provider overlap: sideswap_quote vs sideshift_quote vs changelly_quote, and three separate 'send' tools (lw_send, sideshift_send, changelly_send), plus sideswap_recommend vs sideshift_recommend. An agent must read descriptions carefully to pick the right provider.
A clear, consistent snake_case <prefix>_<verb_noun> pattern runs throughout (jan3_list_sessions, lw_balance, btc_send, sideswap_execute_swap). Minor deviations exist (unified_balance, doctor, qr_decode/qr_generate without a domain prefix), but overall highly predictable.
73 tools is far too many for a single server surface; even accounting for multiple integrated domains (wallet, three swap providers, WapuPay, JAN3 account, QR utilities), this exceeds the 25+ threshold substantially. It likely strains tool selection and context.
The domain (multi-chain wallet + swaps + fiat off-ramp + JAN3 account) is unusually well covered: wallet lifecycle, send/receive/sweep, quotes, execution, status tracking, refunds, and account management are all present. Minor gaps like generic wallet update/rename exist, but coverage is strong.
Maintenance
Related MCP Connectors
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Tenzro Network MCP server: wallet, identity, payments, inference, staking, bridges, verification.
MCP server connecting AI agents to non-custodial staking data across 130+ networks.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server to provide AI agents money functionalities via Nostr and Cashu.666 npm17MIT
- AlicenseAqualityDmaintenanceMCP server that gives AI agents Lightning payments, L402 API access, trust verification, and service discovery.1122 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to send and receive Bitcoin over the Lightning Network using NWC or LND backends.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server giving AI agents Bitcoin and Lightning superpowers for price checks, mempool inspection, Lightning payments, and more.1MIT