hxsteric/mercury

# GitHub Repository: hxsteric/mercury

**URL:** https://github.com/hxsteric/mercury
**Author:** hxsteric
**Description:** Mercury — Blockchain Cash Flow Analyzer | Hermes Agent Skill for multi-chain analysis, fraud detection, trading strategy & interactive WebGL dashboard
**Homepage:** 
**Language:** Python

## Stats
- Stars: 17
- Forks: 1
- Open Issues: 1
- Commits: 1
- Created: 2026-03-15T22:36:04Z
- Updated: 2026-06-14T21:50:43Z
- Pushed: 2026-03-15T22:36:06Z

## README
# 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.

![Mercury Dashboard](https://img.shields.io/badge/Hermes-Skill-blue?style=for-the-badge)
![Chains](https://img.shields.io/badge/Chains-Ethereum%20%7C%20Base%20%7C%20Solana-green?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)

## 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)

```bash
# 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`:

```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

```bash
# 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

| Pattern | Severity | Description |
|---------|----------|-------------|
| Dust Attacks | Medium | Tiny unsolicited token transfers |
| Rapid Transfers | Medium | Burst activity suggesting bots or wash trading |
| Mixer Interaction | Critical | Transfers to/from known mixing services |
| Address Poisoning | High | Dust from addresses mimicking legitimate ones |
| Dormant Activation | Medium | Long-inactive wallet suddenly active |
| High Fan-Out | High | Single-block mass distribution |

## 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](https://nousresearch.com) — March 2026