Skip to main content
Back to scanner

Agent Integration

Give your AI agent the ability to analyze Bitcoin transactions for privacy exposure. CLI tool with JSON output, MCP server for structured tool calls, or import the engine directly.

Quick Start

npm install -g am-i-exposed

Requires Node.js 20+. Or use npx am-i-exposed without installing.

Available Tools

scan_transaction

Run 25 privacy heuristics on a transaction. Detects CoinJoin, change outputs, wallet fingerprints, entity matches, and more.

am-i-exposed scan tx 323df21f...dec2 --json

scan_address

Check address reuse, UTXO hygiene, spending patterns, entity identification, and temporal correlation.

am-i-exposed scan address bc1q... --json

scan_psbt

Analyze an unsigned transaction BEFORE broadcasting. Zero network access needed. The key tool for privacy-aware transaction crafting.

am-i-exposed scan psbt /tmp/proposed-tx.psbt --json

scan_wallet

Wallet-level privacy audit via xpub/zpub/descriptor. Derives addresses, scans activity, checks reuse and UTXO hygiene.

am-i-exposed scan xpub zpub6r... --json --gap-limit 30

compute_boltzmann

Compute Boltzmann entropy, wallet efficiency, and the full link probability matrix. Auto-detects WabiSabi and JoinMarket for turbo mode.

am-i-exposed boltzmann 323df21f...dec2 --json

JSON Output

All commands with --json return a consistent envelope:

{
  "score": 95,
  "grade": "A+",
  "txType": "whirlpool-coinjoin",
  "findings": [
    {
      "id": "h4-whirlpool",
      "severity": "good",
      "title": "Whirlpool CoinJoin detected",
      "scoreImpact": 30,
      "confidence": "deterministic"
    }
  ],
  "recommendation": {
    "urgency": "when-convenient",
    "headline": "Maintain UTXO separation"
  }
}
A+
90-100
B
75-89
C
50-74
D
25-49
F
0-24

MCP Server

For AI agents that support Model Context Protocol - structured tool calls over stdio instead of parsing CLI output.

am-i-exposed mcp

Claude Desktop configuration:

{
  "mcpServers": {
    "bitcoin-privacy": {
      "command": "npx",
      "args": ["-y", "am-i-exposed", "mcp"]
    }
  }
}

Exposes the same 5 tools with typed input schemas (zod validation). Compatible with Claude Desktop, Claude Code, Cline, and other MCP clients.

Agent Workflows

Pre-broadcast privacy check

  1. Craft a transaction in your wallet, export as PSBT
  2. Run: am-i-exposed scan psbt <file> --json
  3. Check .grade - if D or F, modify coin selection
  4. Repeat until grade is B or better, then sign and broadcast

Wallet health audit

  1. Export your xpub/zpub from wallet software
  2. Run: am-i-exposed scan xpub <key> --json --gap-limit 30
  3. Check reusedAddresses (should be 0) and dustUtxos (should be 0)
  4. Review findings for consolidation history and script type mixing

Transaction forensics

  1. Run: am-i-exposed scan tx <txid> --json
  2. Check grade and txType for quick assessment
  3. For deeper analysis: am-i-exposed chain-trace <txid> --depth 3 --json
  4. Review entity proximity and taint findings

Performance

ModeTimeNotes
Normal scan~10sFull context (parent txs + output addresses)
--fast~6sSkip context fetching, all heuristics still run
Cached (repeat)~1.5sSQLite cache, instant on second scan
PSBT (offline)<1sZero network access needed
Boltzmann2-15msRust/WASM, turbo modes for WabiSabi/JoinMarket

Privacy

  • No addresses or transactions are logged or persisted by the CLI
  • Entity detection uses bundled data files (~92 MB), no external APIs
  • PSBT analysis requires zero network access
  • Only mempool.space API is used for blockchain data (or your custom endpoint)
  • All analysis runs locally on your machine
  • Self-host with --api flag pointed at your own mempool instance
skill.md (full docs)CLI source codeFull specnpm package