What is agentic-aqua AGENTS.md?

Project instructions for agentic-aqua, an MCP server for managing Bitcoin and Liquid Network wallets. Liquid is a Bitcoin-related network, and MCP is a way for AI assistants to use connected tools.

They are for working on the wallet server, its command-line interface, tests, scripts, documentation, and related wallet integrations.

They give an AI coding assistant the project’s architecture, file locations, commands, and important development constraints.

How jan3dev/agentic-aqua configures Codex and OpenCode

Reuse

Borrowing it

Nothing to install: this file belongs to jan3dev/agentic-aqua. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/jan3dev/agentic-aqua/main/AGENTS.md

Clone the repo

git clone --depth 1 https://github.com/jan3dev/agentic-aqua

Made for: Codex, OpenCode.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/jan3dev/agentic-aqua/agents-md/github.svg)](https://agentmods.dev/instructions/jan3dev/agentic-aqua/agents-md)

Your own site

<a href="https://agentmods.dev/instructions/jan3dev/agentic-aqua/agents-md"><img src="https://agentmods.dev/badge/instructions/jan3dev/agentic-aqua/agents-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/instructions/jan3dev/agentic-aqua/agents-md"><img src="https://agentmods.dev/badge/instructions/jan3dev/agentic-aqua/agents-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 3,428 This file is loaded in full into every session.

When invoked 3,428 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.03428	$0.03428
Opus 5.5	$0.01371	$0.01371
Sonnet 5.5	$0.00686	$0.00686
Haiku 4.5	$0.00343	$0.00343

Measured 1mo ago against content hash 52f69140a7cc, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

agentic-aqua AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 234 lines

How it starts

The opening of the file, as written. The whole thing — 234 lines — stays where its author put it; the contents beside it link to each section on GitHub.

agentic-aqua

MCP server for managing Liquid Network and Bitcoin wallets through AI assistants (part of AQUA). Liquid via LWK (Blockstream); Bitcoin via BDK. One BIP39 mnemonic backs both networks (unified wallet).

Architecture

AI Assistant ──MCP──▶ aqua.server ──▶ tools.py ──▶ wallet.py  (LWK ─ Electrum/Esplora)
                                              └─▶ bitcoin.py (BDK ─ Esplora)
                                              └─▶ lightning.py / sideshift /
                                                  changelly / wapupay  (third-party clients)

No local node. Liquid: Blockstream Electrum/Esplora. Bitcoin: Esplora only.

Layout

Path	What lives there	Read its `AGENTS.md`
`src/aqua/`	Python package: server, tools, wallets, swap clients	`src/aqua/AGENTS.md`
`src/aqua/cli/`	`aqua` Click CLI (mirrors MCP tool surface)	`src/aqua/cli/AGENTS.md`
`tests/`	pytest suite, fixtures, mock patterns	`tests/AGENTS.md`
`scripts/`	One-off dev/release helpers (incl. `bump_beta.py`)	—
`docs/`	Release & config guides — `PUBLISHING.md` (release/CI flow), `CONFIG.md`	—
`dist/`	Build artifacts (do not edit)	—

Entry points

aqua.server:main — MCP stdio server (registered as aqua-mcp and agentic-aqua).
aqua.cli.main:cli — Click CLI registered as aqua.

Dev commands

uv sync --all-extras                       # install dev deps
uv run python -m pytest tests/             # run full suite
uv run python -m pytest tests/test_x.py    # single file
uv run ruff check src tests                # lint
uv run python -m aqua.server               # run MCP server locally (stdio)
uv run aqua --help                         # CLI surface

Python ≥ 3.13, package manager uv only (never pip/venv directly).

Code invariants (must hold across the codebase)

Amounts are integer satoshis end-to-end. Decimal strings appear only on third-party wires (SideShift, Changelly). Convert at the boundary; never propagate floats inward.
One mnemonic → two wallets. BTC derivation m/84'/0'/0', Liquid m/84'/1776'/0' + SLIP-77 master blinding key. Descriptors are NOT inter-derivable; watch-only setups need both.
TXIDs are returned big-endian (display format). BDK uses little-endian internally; flip at the boundary in bitcoin.py.
At-rest password ≠ BIP39 passphrase. Encrypts the mnemonic file (PBKDF2 480k + Fernet); does NOT change derived keys. Same mnemonic restores in any BIP39 wallet without it.
No silent fallbacks. If signing, broadcasting, or PSET verification fails, raise ValueError (or a specific exception). Do not return a fake-success envelope. See CLAUDE.md "No lies rules".
File perms. ~/.aqua/ is 0o700; wallet/swap files 0o600 (contain secrets or refund keys).
Atomic writes. Wallet/swap files are written via temp file + os.replace.
A Lightning send swap record is the only way back to its locked L-BTC. The refund key is random, not seed-derived, so ~/.aqua/lightning_swaps/*.json cannot be reconstructed from the mnemonic. Anything pay_invoice drops from the provider's response is unrecoverable for that swap — see docs/submarine-swap-ln-refund.md.

Read the full file on GitHub · 234 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

1mo ago Changed · +7 lines · +145 tokens per session 52f69140a7cc
2mo ago First seen · 227 lines · 3,283 tokens per session scan A 90c1d6a6b497

Subscribe to this mod's changes

agentic-aqua AGENTS.md is an instructions file published in the GitHub repository jan3dev/agentic-aqua (6 stars, last pushed yesterday), licensed MIT. It adds 3,428 tokens to every session, about $0.0137 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

ai bitcoin bitcoin-wallet lightning-network liquid-network openclaw

agentic-aqua AGENTS.md next to 6 instructions from other repositories
Mod	Type	Stars	Last push	Licence	Scan	Tokens	Works with
agentic-aqua AGENTS.mdjan3dev/agentic-aqua	Instructions file	6	yesterday	MIT	A	3,428	Codex, OpenCode
vscode buildNext.instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	9,719	GitHub Copilot
next.js AGENTS.mdvercel/next.js	Instructions file	143k	yesterday	MIT	A	7,461	Codex, OpenCode
langchain AGENTS.mdlangchain-ai/langchain	Instructions file	149k	yesterday	MIT	A	4,680	Codex, OpenCode
vscode oss-third-party-notices.instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	5,516	GitHub Copilot
vscode copilot-instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	3,093	GitHub Copilot
deepseek-harness AGENTS.mddeepseek-ai/deepseek-harness	Instructions file	274k	2d ago	MIT	A	4,313	Codex, OpenCode

agentic-aqua: Instructions file for Codex