Agentic AQUA gives AI agents the ability to interact with Bitcoin wallets, including wallets that can hold and spend real funds. That makes the setup process especially important. This guide explains how to use Agentic AQUA in a safer way: keep seed phrases out of the MCP, use the CLI for sensitive wallet actions, prefer watch-only wallets when spending is not needed, and encrypt any wallet file that can sign transactions.

⚠️ Warning: Agentic AQUA is driven by AI agents that can make autonomous spending decisions. Bitcoin and cryptocurrency transactions are irreversible, and an autonomous agent could move funds in ways you cannot undo. Treat any wallet imported into Agentic AQUA as higher-risk than a typical hot wallet. Use it only for small, active spending balances and keep long-term funds separate.

Safety First: Keep Seed Phrases out of the MCP

Agentic AQUA can be used two ways, both backed by the same underlying commands. The CLI is the agentic-aqua command-line tool, where you run wallet operations directly yourself. The MCP server is a local standard input/output server aqua serve that exposes those same operations as tools an AI agent can call, with arguments and results passed through the agent's tool-calling flow.

We strongly recommend that you always handle seed phrases through the CLI, not the MCP. We included CLI workflows in Agentic AQUA for exactly this purpose.

Agentic AQUA connects to AI models that may run in the cloud. Anything you send to the MCP becomes part of the model’s context and may be logged or retained by the model provider, such as Anthropic or OpenAI. So, to be very clear: if you generate a seed phrase with an agent, or paste your seed phrase into a bot, Sam Altman can read it. To prevent this, follow the guidelines below:

1. Import seed phrases with the CLI

If you already have a seed phrase, import it through the CLI, not the MCP.

2. Generate seed phrases with the CLI

If you need a new wallet, generate the seed phrase through the CLI, not the MCP.

Run the CLI locally: your seed phrase is written to ~/.aqua/, and signing happens on your machine, so the seed phrase never leaves your device.

Importing Seed Phrases via CLI

To import a seed phrase from another wallet into Agentic AQUA, run (or ask your agent to run) the following command in your terminal.

uv run aqua wallet import-mnemonic --password-stdin

You'll be prompted to type or paste your seed phrase, then encrypt it with a password. Your input will be hidden:

Mnemonic: ************************
Password: ***********

The wallet is written to `~/.aqua/wallets/default.json`, encrypted with PBKDF2 + Fernet using your password.

Generating Seed Phrases via CLI

To securely generate a new seed phrase, run the following CLI command:

uv run aqua wallet generate-mnemonic

  Output:

json
  {
    "mnemonic": "[twelve words appear here]",
    "words": 12,
    "warning": "Store this mnemonic securely. Anyone with access can control your funds."
  }

Write these words down on paper and store them safely. This is your only guaranteed backup; if your device fails or is lost, or you forget your encryption password, the paper copy is the only way to recover your funds.

You can then use this seed phrase to create a new wallet by using the  `uv run aqua wallet import-mnemonic --password-stdin` command shown earlier. 

Use Watch-only Wallets for Monitoring

If you only want your agent to track transactions, build reports, or generate receive addresses, import a watch-only wallet descriptor instead of the seed. Then your agent will be able to see balances and addresses but won’t be able to spend funds.

There are many ways to get a watch-only wallet. In AQUA (the mobile version), go to Settings -> Wallet Details -> Watch-only Export. If you’re using the Blockstream App (desktop) you would go to Settings -> Watch-only.

Here are examples of how you would import Bitcoin and Liquid watch-only wallets:

Bitcoin:

uv run aqua btc import-descriptor \
  --descriptor "wpkh([112b7713/84'/0'/0']xpub6DGCwdmB1EPcxXuvDDGjDjpjD9YLXoHoXJb77pBS2LiGHB9uzDcuoNBvv8eCqSUBhLCEA8YSVe4miy7AFQu9s99W4x3XAi2LjcSid9Fhq1k/0/*)#3vn98r83" \
  --wallet-name "btc-watch-only-wallet" \
  --network mainnet

Liquid:

uv run aqua liquid import-descriptor \
  --descriptor "ct(slip77(e3dfae9bbce6b034603b7734a290b6f96519f4aa3173c67dccb888ddaf3b27ea),elwpkh([112b7713/84'/1776'/0']xpub6DN92bPm1v6CWe1Kb6SG2bPbsGvs3i5GzYsbhKiVCF4qfct9wSnKLbax3a42USTWbUzCZX5Tp4q5UvX6JhgjmX2rdcJxbY6pd8ToRFNsKp4/<0;1>/*))#4xnyhdus" \
  --wallet-name "liquid-watch-only-wallet" \
  --network mainnet

Wrapping Up

While this guide was written for Agentic AQUA, the same basic rules apply when working with any agentic Bitcoin wallet: keep seed phrases local, use watch-only access when spending is not needed, and encrypt any wallet file that can sign transactions. AI agents can help automate wallet workflows, but real funds still need strict boundaries.