Create a new wallet (both Liquid and Bitcoin) from a freshly generated 12-word seed. The seed is NEVER shown or returned. After creating, recommend that the user back up the seed.

Write the wallet's seed to a local plain-text backup file. Call ONLY when the user explicitly asks to back up the seed. The seed is never returned; never read the file back into the conversation.

Import a wallet from a BIP39 seed phrase (creates both Liquid and Bitcoin wallets from the same seed)

Import a watch-only wallet from a CT descriptor

Export the CT descriptor for a wallet (for watch-only import elsewhere)

Get wallet balance for all assets (L-BTC, USDT, etc.)

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.

Get transaction history

Send L-BTC to an address

Send a Liquid asset (USDT, etc.) to an address

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.

Get the status of a Liquid transaction. Accepts a txid or a Blockstream explorer URL (e.g. https://blockstream.info/liquid/tx/abc123...)

List all wallets

List known Liquid assets (asset_id, ticker, name, precision). Use this to resolve asset IDs for lw_send_asset without a prior balance query.

Permanently delete a wallet, its seed and all its cached data (irreversible). Two-step: call WITHOUT confirm first to get a preview (balances, warning, confirm_token) and delete nothing; show it to the user, ask for explicit confirmation, then call again with confirm=true and that confirm_token. Use the 'delete_wallet' prompt for the safe workflow.

Get Bitcoin wallet balance in Satoshis

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.

Get Bitcoin transaction history

Send BTC to an address

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.

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).

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.

Get balance for both Bitcoin and Liquid networks (unified wallet)

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).

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.

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.

Decode a BOLT11 Lightning invoice without paying it. Returns amount_sats (null for zero-amount invoices), description/message, and expiry_seconds.

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.

Create or reuse a Noviuz Hosted KYC session through Ankara for a logged-in JAN3 account. Returns session_id and verification_url: give the URL to the user unchanged to open in their default browser, and treat both as credentials. Calling again within 30 minutes with the same parameters returns the same session. Returns status='already_verified' when the account already passed KYC. No CPF, name, e-mail, Pix data, documents, status assertion, or EUID is accepted from the client.

Ask Ankara to reconcile a Noviuz Hosted KYC session. Pass only the opaque session_id returned by eulen_kyc_session. Ankara obtains the authoritative status and EUID server-to-server. Poll every 15-20 seconds while session_status is 'created'; under_review is NOT verified. Returns is_final, is_success, poll_after_seconds and next_step.

Create a PIX charge through Ankara that pays DePix to a local Liquid wallet. Requires JAN3 login and approved hosted KYC. amount_cents is the gross PIX amount in BRL cents (100 = R$1.00). Returns PIX Copia e Cola, QR image data, Ankara's dynamic fee breakdown, and swap_id for pix_status.

List PIX → DePix deposits from Ankara's authoritative database and refresh their local cache entries. All filters are optional and combined. To answer requests such as 'today' or 'last week', convert the requested period to inclusive UTC dates in YYYY-MM-DD format and pass date_from/date_to.

Get a PIX → DePix deposit through Ankara, hydrating the local cache when needed. The supplied JAN3 account must own the deposit. Terminal success is depix_sent.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

List Liquid assets that SideSwap supports for atomic swaps (e.g. L-BTC, USDt, EURx, MEX, DePix).

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.

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.

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.

List the coins and networks SideShift supports for cross-chain swaps. Use to discover valid (coin, network) IDs for the other sideshift_* tools.

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.

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.

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.

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.

Check the status of a SideShift shift order. Returns the shift record plus is_final / is_success / is_failed booleans.

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).

Get WapuPay's current exchange rates (e.g. USDT/ARS). Public — no login or API key.

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).

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.

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.

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

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.

List WapuPay transactions (scoped to the WapuPay account/key).

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.

Get the WapuPay account/key's monthly spending limit (USDT), based on KYC tier.

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.

Generate a PNG QR code for arbitrary content and return qr_code_path. Optionally includes a terminal-friendly block QR string.

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.

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.

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.

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).

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.

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).

Return non-sensitive info about a persisted JAN3 session (base_url, created_at, captcha_exempt, token previews).

List all persisted JAN3 sessions (metadata only, no tokens).

Delete a persisted JAN3 session file. Idempotent.

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.

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.

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.

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.

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).