agentic-aqua 0.3.0__py3-none-any.whl

agentic_aqua-0.3.0.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: agentic-aqua
+Version: 0.3.0
+Summary: Agentic AQUA — MCP server for Liquid Network and Bitcoin wallet operations
+Project-URL: Homepage, https://github.com/jan3dev/agentic-aqua
+Project-URL: Repository, https://github.com/jan3dev/agentic-aqua
+Project-URL: Documentation, https://github.com/jan3dev/agentic-aqua#readme
+Author-email: Andy <andy@example.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,bitcoin,blockstream,liquid,lwk,mcp,wallet
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: bdkpython>=2.2.0
+Requires-Dist: click>=8.1
+Requires-Dist: coincurve>=21.0.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: lwk>=0.8.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Agentic AQUA
+
+MCP server and CLI for managing **Liquid Network** and **Bitcoin** wallets through AI assistants like Claude. One mnemonic backs both networks (unified wallet). Also can operates on Lightning network via Boltz swaps.
+
+## Features
+
+- **Generate & Import** - Create new wallets or import existing mnemonics
+- **Unified Wallet** - One mnemonic for Liquid and Bitcoin; `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)
+- **Lightning** - Send and receive via Lightning using L-BTC (via Boltz & Ankara)
+- **Assets** - Native support for L-BTC, USDT, and all Liquid assets
+- **Secure** - Encrypted storage, no remote servers for keys
+
+## Installation
+
+> **Quickest way:** just ask your AI agent directly:
+>
+> ```
+> Install this MCP server: https://github.com/jan3dev/agentic-aqua
+> ```
+
+### Recommended (uvx)
+
+If you don't have `uvx` installed:
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Configure Claude Desktop (`~/.claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agentic-aqua": {
+      "command": "/full/path/to/uvx",
+      "args": ["agentic-aqua"]
+    }
+  }
+}
+```
+
+Find the full path to `uvx` with:
+
+```bash
+which uvx
+# Example: /Users/yourname/.local/bin/uvx
+```
+
+Restart Claude Desktop and you're ready to use Bitcoin and Liquid wallets.
+
+### For Developers
+
+Clone and install from source:
+
+```bash
+git clone https://github.com/jan3dev/agentic-aqua.git
+cd agentic-aqua
+uv sync
+```
+
+Configure Claude Desktop using the full path to `uv` (find with `which uv`):
+
+```json
+{
+  "mcpServers": {
+    "agentic-aqua": {
+      "command": "/full/path/to/uv",
+      "args": ["run", "--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 mnemonic)
+- "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 mnemonic |
+| `lw_import_mnemonic` | Import wallet from mnemonic (also creates Bitcoin wallet) |
+| `lw_import_descriptor` | Import watch-only wallet from CT descriptor |
+| `lw_export_descriptor` | Export CT descriptor for watch-only use |
+| `lw_list_wallets` | List all wallets |
+| `delete_wallet` | Delete a wallet and all its cached data |
+
+**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_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 |
+
+**Unified**
+
+| Tool | Description |
+|------|-------------|
+| `unified_balance` | Get balance for both Bitcoin and Liquid |
+
+**Lightning**
+
+| Tool | Description |
+|------|-------------|
+| `lightning_receive` | Generate a Lightning invoice to receive L-BTC (100–25,000,000 sats) |
+| `lightning_send` | Pay a Lightning invoice using L-BTC via Boltz (~0.1% fee) |
+| `lightning_transaction_status` | Check status of a Lightning swap (send or receive) |
+
+## 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.
+
+```bash
+# Discover commands
+aqua --help
+aqua wallet --help
+aqua btc --help
+aqua liquid --help
+aqua lightning --help
+
+# Wallet management
+aqua wallet generate-mnemonic
+aqua wallet import-mnemonic --wallet-name default --network mainnet
+aqua wallet list
+aqua wallet export-descriptor --wallet-name default
+aqua wallet delete --wallet-name old
+
+# 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 Boltz / Ankara)
+aqua lightning receive --amount 50000
+aqua lightning send --invoice lnbc...
+aqua lightning status --swap-id <id>
+
+# 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 mnemonics safely (env vars from a text file)
+
+Avoid pasting mnemonics into shell prompts or chat with an AI agent — both shell history and agent transcripts may persist them. The recommended workflow is to keep secrets in a local text file with restricted permissions and load them as environment variables.
+
+1. Create `~/.aqua/secrets.env` (or any path you prefer) and lock it down:
+
+   ```bash
+   mkdir -p ~/.aqua
+   cat > ~/.aqua/secrets.env <<'EOF'
+   AQUA_MNEMONIC="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+   AQUA_PASSWORD="Wild-red-dolphin-386"
+   EOF
+   chmod 600 ~/.aqua/secrets.env
+   ```
+
+2. Source it before running CLI commands and clear it afterwards:
+
+   ```bash
+   set -a; . ~/.aqua/secrets.env; set +a
+   aqua-cli wallet import-mnemonic --wallet-name default --network mainnet
+   unset AQUA_MNEMONIC AQUA_PASSWORD
+   ```
+
+   `aqua-cli` also auto-loads a `.env` file from the project root via `python-dotenv` if you prefer a per-project file.
+
+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_<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`:
+
+```bash
+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 mnemonic is no longer needed for day-to-day operations; only `AQUA_PASSWORD` is used to sign transactions.
+
+## 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:
+>
+> ```bash
+> mv ~/.aqua-mcp ~/.aqua
+> ```
+
+```json
+{
+  "network": "mainnet",
+  "default_wallet": "default",
+  "electrum_url": null,
+  "auto_sync": true
+}
+```
+
+## Security
+
+Mnemonics are encrypted at rest using a password (PBKDF2 + Fernet). Without a password, the mnemonic 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 mnemonic, so the same mnemonic restores identical descriptors in any BIP39-compliant wallet (AQUA, Blockstream Green, 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
+
+```bash
+# Install with dev dependencies
+uv sync --all-extras
+
+# Run tests
+uv run 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)
+                       │
+                       └──→ Boltz / Ankara ──→ Lightning
+```
+
+## Credits
+
+Built with:
+- [LWK](https://github.com/Blockstream/lwk) - Liquid Wallet Kit by Blockstream
+- [BDK](https://github.com/bitcoindevkit/bdk-python) - Bitcoin Development Kit
+- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
+- [Boltz](https://boltz.exchange/) - Submarine swaps for Lightning

agentic_aqua-0.3.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+aqua/__init__.py,sha256=FjAAbyjKfcG8H4gclAuCM68qVcFKD-P5O36HclYx51o,109
+aqua/ankara.py,sha256=AUXPzobm_LhOLlJCJjkq1jBs1e-kCN-DF1XIu0kCtSQ,2972
+aqua/assets.py,sha256=UnN-5CZc_Bj3QyCs_dsHMmsXKh0moD10DZjj4GNo32s,3138
+aqua/bitcoin.py,sha256=uqiicA4Sc-b-oi5Gwl6z3KPp-eZg12xjNm-WRrHAQ4M,13836
+aqua/boltz.py,sha256=oomJVqYjTPWAqKTaT-Lpx5gTHoQ6par5Mb6RBw3aa68,5259
+aqua/lightning.py,sha256=KCxR14EEr1z5On7xo6dbpIdi5r-Mv88STVtHtHU93e0,14115
+aqua/server.py,sha256=pPmFU2tjnYxNeIw-tjFPRh89xnLGi1Gv9RKJQFEmCBA,42587
+aqua/storage.py,sha256=yGAcYQKPK79vRfnnGGh12-xWaSZdNoTy330ePBQOazc,12238
+aqua/tools.py,sha256=GSFweNv8V3nta6Vf5k0tGm0QWppZZt2RBaWsp6Q6IKw,22133
+aqua/wallet.py,sha256=nVUjRckY8V_J4qEt8H85KAK8gF8DPSZEvepwKjiJ_ZU,11409
+aqua/cli/__init__.py,sha256=iDaGtdJuhg5j7eV4H_EARyjSIUNWM-uWx0ZpcCE9XUU,90
+aqua/cli/btc.py,sha256=yMSkiR2MprUnnCRBhCzDFupPLzpsfh5EmcIehKffWwA,2605
+aqua/cli/commands.py,sha256=CSzabNlYzXGJqzc8W1lJJNlPY4VtzXOwP1An6r51ts8,857
+aqua/cli/lightning.py,sha256=dMJZ5JkPtSEMMcH8Idm-uYIpkeJEIQygYI_j-JOC-xc,2641
+aqua/cli/liquid.py,sha256=Zs32RdDnN8zQ8FpYfNwBhQwhqT0DfS5blL_8BpAcKtE,6072
+aqua/cli/main.py,sha256=pP1pbJRUwtkO3_oE9vza7uBWb0BZ2fUvZnFfQGTkwt0,1360
+aqua/cli/output.py,sha256=FWa-5SUsxkJ8or7GqMDx1BZEH0mL64Y_SN_dC20kU58,2167
+aqua/cli/password.py,sha256=JiSZAhqEUHuoaRzA-_TY3MT7A1l3FujZnm46SDl00S4,1556
+aqua/cli/serve.py,sha256=v6dX5D5gg61orH_1hOHqo7EGVuieC7a3G1QR06LIvFI,261
+aqua/cli/wallet.py,sha256=xA4MwyCt9ynABBTgFxORThZktc1YgKTJGIsic1_8hnA,4478
+agentic_aqua-0.3.0.dist-info/METADATA,sha256=pneU99x5bYMMFRyexJZG5MkRQ-0E2PdIYwNDqECYIWw,10694
+agentic_aqua-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentic_aqua-0.3.0.dist-info/entry_points.txt,sha256=daLwm0HZ381CB4DGSxTYMOAd6LEeVjXOds9jeRk8Ntg,71
+agentic_aqua-0.3.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+agentic_aqua-0.3.0.dist-info/RECORD,,

agentic_aqua-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentic_aqua-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+aqua = aqua.cli.main:cli
+aqua-mcp = aqua.server:main

agentic_aqua-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aqua/__init__.py

@@ -0,0 +1,3 @@
+"""Agentic AQUA - Manage Liquid Network and Bitcoin wallets through AI assistants."""
+
+__version__ = "0.3.0"

aqua/ankara.py

@@ -0,0 +1,90 @@
+"""Ankara backend integration for Lightning → L-BTC swaps."""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+# API URL with environment variable override
+ANKARA_API_URL = os.environ.get("ANKARA_API_URL", "https://ankara.aquabtc.com")
+
+
+@dataclass
+class AnkaraSwapInfo:
+    """Holds all data for an active/completed Ankara Lightning swap."""
+
+    swap_id: str
+    boltz_swap_id: str
+    invoice: str
+    address: str
+    amount: int
+    wallet_name: str
+    status: str  # "pending" | "settled" | "failed"
+    created_at: str
+    preimage: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AnkaraSwapInfo":
+        return cls(**data)
+
+
+class AnkaraClient:
+    """HTTP client for Ankara backend API."""
+
+    def __init__(self):
+        self.base_url = ANKARA_API_URL
+
+    def _api_request(self, method: str, path: str, body: dict | None = None) -> dict:
+        """Make HTTP request to Ankara API."""
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode() if body else None
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": "agentic-aqua",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            # Try to extract error message from response body
+            detail = ""
+            try:
+                err_body = json.loads(e.read().decode())
+                detail = err_body.get("error", err_body.get("message", ""))
+            except Exception:
+                pass
+            msg = f"Ankara API error ({e.code} {method} {path})"
+            if detail:
+                msg += f": {detail}"
+            raise RuntimeError(msg) from e
+        except urllib.error.URLError as e:
+            raise RuntimeError(f"Ankara API unreachable ({method} {path}): {e.reason}") from e
+
+    def create_swap(self, amount: int, address: str) -> dict:
+        """POST /api/v1/lightning/swaps/create/ - create a new swap."""
+        return self._api_request(
+            "POST",
+            "/api/v1/lightning/swaps/create/",
+            {
+                "amount": amount,
+                "address": address,
+            },
+        )
+
+    def claim_swap(self, swap_id: str) -> dict:
+        """POST /api/v1/lightning/swaps/{swap_id}/claim/ - claim a swap."""
+        return self._api_request("POST", f"/api/v1/lightning/swaps/{swap_id}/claim/")
+
+    def verify_swap(self, swap_id: str) -> dict:
+        """GET /api/v1/lightning/lnurlp/verify/{swap_id} - verify swap status."""
+        return self._api_request("GET", f"/api/v1/lightning/lnurlp/verify/{swap_id}")

aqua/assets.py

@@ -0,0 +1,92 @@
+"""Known Liquid Network asset registry."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class AssetInfo:
+    """Metadata for a known Liquid asset."""
+
+    asset_id: str
+    name: str
+    ticker: str
+    logo: str
+    precision: int  # Number of decimal places (e.g. 8 means divide by 10^8)
+
+
+# Mainnet known assets
+MAINNET_ASSETS: dict[str, AssetInfo] = {
+    info.asset_id: info
+    for info in [
+        AssetInfo(
+            asset_id="6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d",
+            name="Liquid Bitcoin",
+            ticker="L-BTC",
+            logo="https://aqua-asset-logos.s3.us-west-2.amazonaws.com/L-BTC.svg",
+            precision=8,
+        ),
+        AssetInfo(
+            asset_id="ce091c998b83c78bb71a632313ba3760f1763d9cfcffae02258ffa9865a37bd2",
+            name="Tether USDt",
+            ticker="USDt",
+            logo="https://aqua-asset-logos.s3.us-west-2.amazonaws.com/USDt.svg",
+            precision=8,
+        ),
+        AssetInfo(
+            asset_id="3438ecb49fc45c08e687de4749ed628c511e326460ea4336794e1cf02741329e",
+            name="JPY Stablecoin",
+            ticker="JPYS",
+            logo="https://aqua-asset-logos.s3.us-west-2.amazonaws.com/JPYS.svg",
+            precision=8,
+        ),
+        AssetInfo(
+            asset_id="18729918ab4bca843656f08d4dd877bed6641fbd596a0a963abbf199cfeb3cec",
+            name="PEGx EURx",
+            ticker="EURx",
+            logo="https://aqua-asset-logos.s3.us-west-2.amazonaws.com/EURx.svg",
+            precision=8,
+        ),
+        AssetInfo(
+            asset_id="26ac924263ba547b706251635550a8649545ee5c074fe5db8d7140557baaf32e",
+            name="Mexas",
+            ticker="MEX",
+            logo="https://aqua-asset-logos.s3.us-west-2.amazonaws.com/MEX.svg",
+            precision=8,
+        ),
+        AssetInfo(
+            asset_id="02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189",
+            name="DePix",
+            ticker="DePix",
+            logo="https://aqua-asset-logos.s3.us-west-2.amazonaws.com/DePix.svg",
+            precision=8,
+        ),
+    ]
+}
+
+# Testnet known assets (policy asset only for now)
+TESTNET_ASSETS: dict[str, AssetInfo] = {}
+
+
+def lookup_asset(asset_id: str, network: str = "mainnet") -> Optional[AssetInfo]:
+    """Look up asset metadata by ID. Returns None if unknown."""
+    registry = MAINNET_ASSETS if network == "mainnet" else TESTNET_ASSETS
+    return registry.get(asset_id)
+
+
+def resolve_asset_name(asset_id: str, network: str = "mainnet") -> str:
+    """Return ticker if known, otherwise truncated asset ID."""
+    info = lookup_asset(asset_id, network)
+    if info:
+        return info.ticker
+    return asset_id[:8] + "..."
+
+
+def lookup_asset_by_ticker(ticker: str, network: str = "mainnet") -> Optional[AssetInfo]:
+    """Look up asset metadata by ticker (case-insensitive). Returns None if unknown."""
+    registry = MAINNET_ASSETS if network == "mainnet" else TESTNET_ASSETS
+    target = ticker.lower()
+    for info in registry.values():
+        if info.ticker.lower() == target:
+            return info
+    return None