hxsteric/mercury

Mercury — Blockchain Cash Flow Analyzer

A Hermes Agent skill for multi-chain blockchain cash flow analysis, fraud detection, trading strategy generation, and real-time interactive dashboards.

Features

• Multi-Chain Support — Ethereum, Base, and Solana transaction fetching
• Cash Flow Analysis — Period-by-period inflow/outflow breakdown, token distribution, top counterparties
• Fraud Detection — 6 pattern detectors (dust attacks, rapid transfers, mixer interaction, address poisoning, dormant activation, high fan-out)
• Trading Strategy — AI-generated trading insights based on wallet behavior patterns
• Interactive Dashboard — Three-layer WebGL + Canvas + HTML dashboard with:
  • SpectraNoise-inspired neural network noise background
  • Live network particle animation with mouse interaction
  • v0-style stat cards, gauges, charts, and risk grid
• Hermes Subagents — Parallel execution with delegate_task for maximum speed

Installation

Quick Install (for Hermes Agent users)

# Clone into your Hermes skills directory
git clone https://github.com/YOUR_USERNAME/mercury.git ~/.hermes/skills/data-science/blockchain-cashflow

API Keys

Add your API keys to ~/.hermes/.env:

ETHERSCAN_API_KEY=your_etherscan_key    # Free at https://etherscan.io/apis
BASESCAN_API_KEY=your_basescan_key      # Free at https://basescan.org/apis
HELIUS_API_KEY=your_helius_key          # Free at https://helius.dev

The scripts auto-load keys from ~/.hermes/.env — no manual export needed.

Usage

With Hermes Agent (Recommended)

Just tell your Hermes agent:

Analyze wallet 0x8a4ff766a5dfb16d9dbd6a31f950c48a0caf0f54

The agent will automatically:

1. Detect the chain (Ethereum/Base/Solana)
2. Fetch all transactions using parallel subagents
3. Run cash flow analysis + fraud detection simultaneously
4. Generate a trading strategy
5. Launch the interactive dashboard

Standalone Scripts

# 1. Fetch transactions
python3 scripts/fetch_transactions.py \
  --address 0x8a4ff766a5dfb16d9dbd6a31f950c48a0caf0f54 \
  --chain ethereum \
  --include-tokens \
  --output /tmp/bc_txns.json

# 2. Analyze cash flow
python3 scripts/cashflow_analyzer.py \
  --input /tmp/bc_txns.json \
  --address 0x8a4ff766a5dfb16d9dbd6a31f950c48a0caf0f54 \
  --output /tmp/bc_cashflow.json

# 3. Detect fraud patterns
python3 scripts/fraud_detector.py \
  --input /tmp/bc_txns.json \
  --address 0x8a4ff766a5dfb16d9dbd6a31f950c48a0caf0f54 \
  --output /tmp/bc_fraud.json

# 4. Generate trading strategy
python3 scripts/trading_strategy.py \
  --cashflow /tmp/bc_cashflow.json \
  --fraud /tmp/bc_fraud.json \
  --output /tmp/bc_strategy.json

# 5. Launch dashboard
python3 scripts/dashboard_server.py \
  --cashflow /tmp/bc_cashflow.json \
  --fraud /tmp/bc_fraud.json

Architecture

Mercury Skill
├── SKILL.md                    # Hermes skill definition (YAML frontmatter + instructions)
├── scripts/
│   ├── fetch_transactions.py   # Multi-chain transaction fetcher (Etherscan V2 / Helius)
│   ├── cashflow_analyzer.py    # Period-by-period cash flow analysis
│   ├── fraud_detector.py       # 6-pattern fraud detection engine
│   ├── trading_strategy.py     # Trading strategy generator
│   ├── visualizer.py           # Terminal-based ASCII visualization
│   ├── dashboard_server.py     # Python HTTP server for the dashboard
│   └── dashboard.html          # Three-layer interactive dashboard
└── README.md

Dashboard Preview

The dashboard features three animation layers:

• Layer 0: WebGL fragment shader with fbm noise, domain warping, scanlines, and film grain
• Layer 1: Canvas 2D network particles with proximity connections and mouse attraction
• Layer 2: Dashboard UI with stat cards, flow network map, circular gauges, charts, and risk grid

Fraud Detection Patterns

Requirements

• Python 3.8+
• No external dependencies (stdlib only!)
• Hermes Agent (for subagent orchestration)

License

MIT

Credits

Built for the Nous Research Hermes Agent Hackathon — March 2026