Skip to main content
Glama
Agentic AQUA

Agentic AQUA

by jan3dev

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_balance shows both

  • Bitcoin (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.

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-aqua

This creates a permanent agentic-aqua executable. Find its full path with:

which agentic-aqua
# Example: /Users/yourname/.local/bin/agentic-aqua

Configure 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-aqua to update, uv tool uninstall agentic-aqua to 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.13

Configure 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

lw_generate_mnemonic

Generate new BIP39 seed

lw_import_mnemonic

Import wallet from seed (also creates Bitcoin wallet)

lw_import_descriptor

Import watch-only Liquid wallet from CT descriptor

lw_export_descriptor

Export Liquid CT descriptor for watch-only use

btc_import_descriptor

Import watch-only Bitcoin wallet from BIP84 descriptor

btc_export_descriptor

Export Bitcoin BIP84 descriptors + xpub

lw_list_wallets

List all wallets

delete_wallet

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

lw_balance

Get wallet balances (all assets)

lw_address

Generate Liquid receive address (lq1...)

lw_send

Send L-BTC

lw_send_asset

Send any Liquid asset (USDt, etc.)

lw_sweep

Sweep the entire L-BTC (or one asset) balance to one address

lw_list_assets

List known Liquid assets (asset_id, ticker, name, precision)

lw_transactions

Transaction history

lw_tx_status

Get transaction status (txid or explorer URL)

Bitcoin (btc_*)

Tool

Description

btc_balance

Get Bitcoin balance (sats)

btc_address

Generate Bitcoin receive address (bc1...)

btc_transactions

Bitcoin transaction history

btc_send

Send BTC

btc_sweep

Sweep the entire Bitcoin balance to one address

Unified

Tool

Description

unified_balance

Get balance for both Bitcoin and Liquid

Lightning

Tool

Description

lightning_send

Pay a Lightning invoice or Lightning Address using L-BTC (~0.1% + ~21 Sats)

lightning_transaction_status

Check status of a Lightning swap (send or receive)

lightning_refund

Recover the L-BTC locked up by a failed send swap

lightning_decode

Decode a BOLT11 invoice without paying it

lightning_receive

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

sideswap_server_status

Live fees, peg minimums, hot-wallet balance

sideswap_recommend

Recommend a peg vs an instant swap for a BTC ↔ L-BTC conversion

sideswap_peg_quote

Quote the receive amount for a peg at current fees

sideswap_peg_in

Peg BTC → L-BTC

sideswap_peg_out

Peg L-BTC → BTC

sideswap_peg_status

Check status of a peg order

sideswap_list_assets

List Liquid assets SideSwap supports for atomic swaps

sideswap_quote

Read-only price quote for a Liquid asset swap

sideswap_execute_swap

Execute an atomic Liquid asset swap (L-BTC ↔ USDt, etc.)

sideswap_swap_status

Check status of an atomic asset swap

Swaps — SideShift (sideshift_*) — custodial cross-chain swaps (USDt across chains, BTC ↔ USDt-on-X)

Tool

Description

sideshift_list_coins

List supported coins and networks

sideshift_pair_info

Rate / min / max for a pair

sideshift_quote

Fixed-rate quote (~15 min TTL)

sideshift_recommend

Recommend SideSwap vs SideShift for a pair

sideshift_send

Send funds from the wallet via a fixed-rate shift

sideshift_receive

Receive into the wallet via a variable-rate shift

sideshift_status

Check status of a shift order

Swaps — Changelly (changelly_*) — USDt-Liquid ↔ USDt on Ethereum/Tron/BSC/Solana/Polygon

Tool

Description

changelly_list_currencies

List currencies Changelly supports

changelly_quote

Fixed-rate quote for a USDt-Liquid ↔ USDt-on-X swap

changelly_send

Send USDt-Liquid out to USDt on another chain

changelly_receive

Receive USDt-Liquid from USDt on another chain

changelly_status

Check status of a swap order

WapuPay (wapupay_*) — pay Argentine bank accounts in ARS, funded with USDT or L-BTC on Liquid

Tool

Description

wapupay_exchange_rates

Current exchange rates (e.g. USDT/ARS); public, no key needed

wapupay_quote

Preview USDT cost, fee, and rate for an ARS payment

wapupay_create_order

Create a direct-fiat order (USDT or L-BTC rail); returns a Liquid funding address

wapupay_fund_order

Re-issue funding instructions for an existing order

wapupay_order_status

Check a direct-fiat order's status

wapupay_orders

List locally-tracked orders

wapupay_transactions

List WapuPay transactions

wapupay_transaction

Get a single transaction by id

wapupay_spending_limit

Monthly spending limit (USDT) for the account/key

wapupay_provision_account

Provision a WapuPay API key via your JAN3 account

JAN3 Account (jan3_*) — login, sessions, and Lightning Address for your JAN3 account

Tool

Description

jan3_login / jan3_verify

Default login flow: email OTP → verify, saves the session

jan3_login_start / jan3_login_complete

Fallback paid captchaless login flow

jan3_session_info

Status/metadata for a persisted session

jan3_list_sessions

List all persisted sessions

jan3_logout

Delete a persisted session

jan3_user_info

Account profile + Lightning Address status

jan3_enable_lightning_address

Enable/disable the Lightning Address

jan3_rebind_wallet

Re-bind Lightning Address delivery to a different wallet (destructive)

jan3_ln_check_username

Check if a Lightning username is available

jan3_purchase_ln_username

Buy/update the Lightning username (on-chain payment)

Utilities

Tool

Description

qr_generate

Generate a PNG QR code for any content (address, invoice, URI)

qr_decode

Decode a QR code from an image file

doctor

Diagnose (and optionally repair) the ~/.aqua/config.json config file

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 entrypoint

Output 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-stdin

The CLI honors these variables out of the box:

Variable

Used by

AQUA_MNEMONIC

wallet import-mnemonic

AQUA_PASSWORD

wallet import-mnemonic, btc send, liquid send, liquid send-asset, lightning send, lightning receive

AQUA_LIGHTNING_PROVIDER

lightning send — overrides lightning_provider (indra | boltz)

INDRA_API_URL

Base URL of the Indra swap service (default https://indra.aquabtc.com)

AQUA_<OPTION>

Any CLI option (Click auto_envvar_prefix="AQUA") — e.g. AQUA_WALLET_NAME=default

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-stdin

Tips:

  • Never commit .env or secrets.env files (the project's .gitignore already excludes them).

  • Prefer set -a; . file; set +a over export $(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_PASSWORD is 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 123456

Once logged in:

aqua jan3 list-sessions
aqua jan3 user-info --email you@example.com
aqua jan3 logout --email you@example.com

Configuration

Default config location: ~/.aqua/config.json

Migrating from aqua-mcp? The config dir moved from ~/.aqua-mcp to ~/.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:

  1. Generate wallet on an air-gapped device

  2. Export the CT descriptor

  3. 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 ──→ Lightning

Credits

Built with:

  • LWK - Liquid Wallet Kit by Blockstream

  • BDK - Bitcoin Development Kit

  • MCP - Model Context Protocol

  • Boltz - Submarine swap protocol for Lightning

Available Tools

73 tools
btc_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

    B3.4/5.0

    Scored across 73 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI agents to send and receive Bitcoin over the Lightning Network using NWC or LND backends.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server giving AI agents Bitcoin and Lightning superpowers for price checks, mempool inspection, Lightning payments, and more.
      1
      MIT