aegis-scan

pip install aegis-scan

╭─ Aegis Scan verdict ──────────────────────────────╮
│  CAUTION   risk score 43                              │
╰───────────────────────────────────────────────────────╯

The Problem

Robinhood Chain launched July 2026 as a permissionless Arbitrum-Orbit L2. Permissionless + brand new = risk:

Aegis turns these into a 21-check battery that runs in seconds before you sign.

How It Works

                          ┌─────────────────────────────────────────────┐
                          │            Check Battery (21 checks)        │
                          │                                             │
  ┌──────────┐            │  Contract ── code? owner? supply? honeypot? │
  │   CLI    │  Trade     │  Pool ────── exists? paired? liquid?        │          ┌──────────┐
  │  typer   │──Request──▶│  Execution ─ chain-id? size? MEV context    │──Score──▶│  Engine  │
  │  + rich  │            │  Concentration ─ self-hold? burned?         │          │ decide() │
  └──────────┘            │  Stock ────── disclosure? divergence?       │          └────┬─────┘
                          └─────────────────────────────────────────────┘               │
                                                                                Verdict │
                                                                            (deterministic)
                                                                                       │
                                                                                ┌──────▼──────┐
                                                                                │ AI Summary  │
                                                                                │   Claude    │
                                                                                │ (optional)  │
                                                                                └─────────────┘

Key design: the verdict is deterministic — any DANGER → NO, score thresholds for CAUTION/NO. Claude only explains findings; it never overrides the gate. No API key? Template fallback. Fully offline.

Check Reference

Quick Start

git clone https://github.com/devvtr/aegis
cd aegis
python -m venv .venv && source .venv/bin/activate
pip install -e '.[ai,dev]'       # drop [ai] to skip Claude summaries
cp .env.example .env             # set AEGIS_RPC_URL

Dependencies: httpx pydantic typer rich — no web3. Optional: anthropic.

Usage

# Verify RPC connectivity
aegis doctor

# Scan a buy
aegis scan \
  --token 0xTokenAddr \
  --quote 0xUSDGAddr  \
  --amount 2500       \
  --pool  0xPoolAddr  \
  --direction buy

# JSON for scripting (exit: 0=GO, 1=CAUTION, 2=NO)
aegis scan --token 0x.. --quote 0x.. --amount 500 --json --no-ai

╭─ Aegis verdict ─────────────────────────────────╮
│  CAUTION   risk score 43                             │
╰──────────────────────────────────────────────────────╯
Proceed carefully — the scanner found notable risks.

Key risks
  • Token has an active owner: An owner address can pause transfers…
  • Trade size: large (>= $100k): split or route via an aggregator…
  • AAPL may be a tokenized equity (debt instrument)

Verify yourself
  → Confirm the token and pool addresses against the official source.
  → Check the pool's real depth for your size on the DEX UI.
  → Set a tight slippage limit; split large orders.

┌─ Findings ───────────────────────────────────────────┐
│ check              │ sev    │ finding                 │
│ EXEC-CHAINID       │ ok     │ Chain id verified       │
│ CONTRACT-EXISTS    │ ok     │ Contract code present   │
│ CONTRACT-OWNER     │ warn   │ Active owner detected   │
│ CONTRACT-HONEYPOT  │ ok     │ Transfer sim passed     │
│ CONC-SELF          │ ok     │ Self-holding negligible │
│ POOL-LIQUIDITY     │ ok     │ Active liquidity OK     │
│ EXEC-SIZE          │ warn   │ Trade size: large       │
│ STOCK-DISCLOSURE   │ warn   │ Tokenized equity (debt) │
│ EXEC-MEV           │ info   │ FCFS — reduced MEV      │
└──────────────────────────────────────────────────────┘

╭─ Aegis verdict ─────────────────────────────────╮
│  NO   risk score 190                              │
╰──────────────────────────────────────────────────────╯
High-risk trade — the scanner flagged blocking issues.

Key risks
  • Honeypot risk — transfer() reverts
  • Token self-holds 65% of supply

Configuration

All settings via env vars (prefix AEGIS_) or .env — see .env.example.

Strictness

By default the scanner is strict on every chain — thin liquidity, low volume and oversized-trade signals block (NO), so a genuinely risky token can't slip through as GO.

Optional new-chain leniency relaxes only those market-maturity signals to CAUTION (a freshly-launched chain legitimately has thin books). It is opt-in; security signals — honeypot, hidden transfer fee, mint capability, owner permission — always force NO regardless.

• aegis scan 0x… --lenient — relax market-maturity gates for this scan
• aegis scan 0x… --strict — force strictness (this is already the default)

Use it from an AI agent (MCP)

Aegis ships an MCP server, so any MCP-compatible agent — Claude Desktop, Claude Code, Cursor, Cline, Windsurf, or your own agent built on the OpenAI/Anthropic SDKs — can scan tokens directly. The agent gets the same verdict the CLI produces, new-chain leniency included.

Tools exposed: scan_token (GO / CAUTION / NO with evidence), check_rpc, list_chains. Read-only — it never signs, holds funds or trades.

Install:

pip install "aegis-scan[mcp]"      # then the command `aegis-mcp` is available
# or run with no install:
uvx --from "aegis[mcp]" aegis-mcp

Add it to your agent's MCP config (Claude Desktop claude_desktop_config.json, Cursor ~/.cursor/mcp.json, etc.) — the shape is the same everywhere:

{
  "mcpServers": {
    "aegis": {
      "command": "uvx",
      "args": ["--from", "aegis[mcp]", "aegis-mcp"]
    }
  }
}

If you installed with pip, you can point straight at the command instead:

{
  "mcpServers": {
    "aegis": { "command": "aegis-mcp" }
  }
}

Then just ask your agent: "scan 0x87E1…636B on Robinhood Chain before I buy" — it calls scan_token and reports back the verdict.

Download it as a skill

Prefer a drop-in file over pip? Two Agent Skill archives are attached to each release — unzip the aegis/ folder into your agent's skills directory (~/.claude/skills/):

• aegis-skill.zip (thin, ~2 KB) — installs the latest aegis from PyPI on first use. Needs internet.
• aegis-skill-offline.zip (~42 MB) — bundles the package and all dependencies (Linux / macOS / Windows, Python 3.10–3.13) for an airgapped, version-pinned install.

Rebuild both with bash skill/build.sh. The archive sources live in skill/.

Development

ruff check src tests            # lint
ruff format --check src tests   # format check
pytest -q                       # 156 tests

See CONTRIBUTING.md for the check protocol, severity guide, and PR conventions.

Roadmap

• Tick-by-tick depth simulation (Uniswap V3 tick math)
• Live USD/equity price oracles for divergence measurement
• Holder-concentration via indexer (Blockscout / Dune)
• Bytecode pattern analysis (proxy detection, exploit signatures)
• Multi-venue routing comparison (Uniswap vs Pleiades vs 0x)
• Telegram / Discord bot interface
• Watch mode — continuous token monitoring

Project Structure

aegis/
├── src/aegis/
│   ├── checks/
│   │   ├── contract.py        # code, owner, supply
│   │   ├── honeypot.py        # transfer/approve simulation
│   │   ├── concentration.py   # self-holding, burned supply
│   │   ├── pool.py            # exists, liquidity, pair integrity
│   │   ├── execution.py       # chain-id, size, MEV context
│   │   ├── stock_token.py     # disclosure, divergence
│   │   ├── reputation.py      # GoPlus-backed checks
│   │   └── market.py          # DexScreener-backed checks
│   ├── engine.py              # verdict decision (deterministic)
│   ├── ai.py                  # Claude summary layer
│   ├── rpc.py                 # minimal JSON-RPC client
│   ├── sources/
│   │   ├── goplus.py          # GoPlus Security API client
│   │   └── dexscreener.py     # DexScreener market data client
│   ├── cli.py                 # typer CLI
│   ├── config.py              # pydantic-settings
│   └── models.py              # core types
├── tests/                     # 152 tests
├── docs/architecture.md
├── examples/sample_output.md
└── .github/workflows/ci.yml   # ruff + pytest on 3.10-3.12