# CryptoGuard **Crypto risk scanner that detected every major crash in backtesting — 27 days early, on average.** Scan any token by name, ticker, or contract address. Get a deterministic verdict: **PROCEED / CAUTION / BLOCK**. **Version**: 0.6.0  |  **Live API**: [`https://gpartin--cryptoguard-api-fastapi-app.modal.run`](https://gpartin--cryptoguard-api-fastapi-app.modal.run/health)  |  **Free tier**: 5 calls/day  |  **MCP**: 7 tools --- ## Backtest Results Tested against 7 historical crypto crashes (LUNA, FTX, Celsius, 3AC, UST, SOL/FTX, TITAN) and 4 calm-market control periods. Full methodology and data: [CryptoGuard backtest](https://github.com/gpartin/CryptoGuard/tree/main/backtest). | Method | Recall | Avg Lead Time | False Positive Rate | |--------|--------|---------------|---------------------| | **CryptoGuard (WaveGuard engine)** | **100% (7/7)** | **27.4 days** | **6.1%** | | Z-score baseline | 100% (7/7) | 28.4 days | 29.9% | | Rolling volatility | 86% (6/7) | 15.5 days | 4.0% | **5× fewer false alarms** than statistical baselines with the same recall. ### Example: FTX Collapse (November 2022) On **October 16, 2022**, FTT was trading at $23.73. Z-score analysis saw nothing (score 1.20, PROCEED). **CryptoGuard flagged CAUTION** (anomaly score 4.72). The next day it escalated to BLOCK. **23 days later**, FTX collapsed. FTT fell 94%. --- ## Install ```bash pip install CryptoGuardClient ``` ## Quick Start ```python from cryptoguard import CryptoGuardClient client = CryptoGuardClient() # Validate a trade — primary use case result = client.validate_trade("bitcoin", action="buy", amount_usd=1000) print(result["verdict"]) # PROCEED / CAUTION / BLOCK # Scan a token scan = client.scan("solana") print(scan["risk_level"]) # Rug pull check rug = client.rug_check("solana", "0xabc123...") print(rug["risk_score"]) # Check free tier remaining print(client.free_tier()) ``` ## Primary Endpoint ```bash curl -X POST https://gpartin--cryptoguard-api-fastapi-app.modal.run/v1/validate-trade \ -H "Content-Type: application/json" \ -d '{"token": "solana", "action": "buy", "amount_usd": 500}' ``` First 5 calls/day are free. After that: **$0.05/call** via [x402](https://github.com/coinbase/x402) USDC, or via [RapidAPI](https://rapidapi.com/). ## MCP Integration (Claude Desktop / AI Agents) CryptoGuard is an MCP server with 7 tools. Works with Claude Desktop, Cursor, or any MCP client. ### Option 1: Remote HTTP (no install) ```json { "mcpServers": { "cryptoguard": { "url": "https://gpartin--cryptoguard-api-fastapi-app.modal.run/mcp", "transport": "http" } } } ``` ### Option 2: uvx ```json { "mcpServers": { "cryptoguard": { "command": "uvx", "args": ["--from", "CryptoGuardClient", "cryptoguard-mcp"] } } } ``` ### Option 3: pip install ```json { "mcpServers": { "cryptoguard": { "command": "python", "args": ["-m", "mcp_server.server"] } } } ``` ### MCP Tools | Tool | Description | |------|-------------| | `cryptoguard_validate_trade` | Validate a trade → PROCEED / CAUTION / BLOCK | | `cryptoguard_scan_token` | Anomaly scan for any token | | `cryptoguard_validate_trade_plus` | Premium stateless decision bundle with what-if analysis | | `cryptoguard_counterfactual_trade` | What-if sensitivity analysis with tipping-point guidance | | `cryptoguard_rug_check` | DEX pair rug pull risk assessment | | `cryptoguard_search` | Search tokens by name/symbol/address | | `cryptoguard_health` | Service health check | ## All Endpoints | Method | Endpoint | Price | Description | |--------|----------|-------|-------------| | POST | `/v1/validate-trade` | 5 free/day, then $0.05 | **Primary** — single verdict for AI agents | | POST | `/v1/validate-trades` | 5 free/day, then $0.05 | Batch validate up to 20 trades | | GET | `/v1/scan/{coin_id}` | 5 free/day, then $0.05 | Single token anomaly scan | | POST | `/v1/portfolio/scan` | 5 free/day, then $0.05 | Portfolio batch scan (up to 50 tokens) | | GET | `/v1/scan/{coin_id}/history` | 5 free/day, then $0.05 | Historical self-comparison | | GET | `/v1/rug-check/{chain}/{pair_address}` | 5 free/day, then $0.05 | Rug pull risk assessment | | GET | `/v1/dex/new-pairs` | 5 free/day, then $0.05 | New DEX pair discovery | | GET | `/v1/dex/search` | 5 free/day, then $0.05 | DexScreener pair search | | GET | `/v1/dex/pair/{chain}/{pair_address}` | 5 free/day, then $0.05 | DEX pair details | | GET | `/v1/dex/token/{token_address}` | 5 free/day, then $0.05 | DEX token info | | POST | `/v1/intel/validate-trade-plus` | $0.10/call | Premium stateless decision bundle | | POST | `/v1/intel/counterfactual-trade` | $0.08/call | What-if sensitivity analysis | | GET | `/v1/track-record` | Free | Historical prediction track record | | POST | `/v1/trend-detect` | 5 free/day, then $0.05 | Physics-based trend detection | | POST | `/v1/regime-detect` | 5 free/day, then $0.05 | Regime change detection | | POST | `/v1/correlation-scan` | 5 free/day, then $0.05 | Anomalous correlation detection | | POST | `/v1/volatility-forecast` | 5 free/day, then $0.05 | Physics-based volatility forecast | | POST | `/v1/spectral-scan` | 5 free/day, then $0.05 | Hidden periodicity detection | | POST | `/v1/whale-detector` | 5 free/day, then $0.05 | Whale activity detection | | POST | `/v1/momentum-pulse` | 5 free/day, then $0.05 | Momentum pulse detection | | GET | `/v1/search?q=...` | Free | Search tokens by name | | GET | `/v1/free-tier` | Free | Check remaining free calls | | GET | `/v1/pricing` | Free | Pricing details | | GET | `/v1/stats` | Free | Service statistics | | GET | `/health` | Free | Health check | | POST | `/mcp` | Free | MCP endpoint (JSON-RPC 2.0) | | GET | `/mcp/tools` | Free | List MCP tools | | GET | `/v1/agent/tools` | Free | Agent tool catalog | | GET | `/v1/agent/mcp` | Free | MCP server metadata | ## How It Works 1. **Resolves** token input — CoinGecko ID, ticker symbol, or contract address (7 chains) 2. **Fetches** live market data from CoinGecko + DexScreener 3. **Builds baseline** from tier-matched peers (microcaps vs microcaps, large caps vs large caps) 4. **Extracts** 10 time-series features per day (price ratios, volume dynamics, momentum, volatility) 5. **Runs anomaly detection** — GPU-accelerated WaveGuard engine scores each token against its peer baseline 6. **Multi-check pipeline**: peer scan + rug pull + history + CEX/DEX spread + concentration risk 7. **Returns verdict**: PROCEED / CAUTION / BLOCK with anomaly scores and top contributing features
About the detection engine CryptoGuard's core scanner is powered by [WaveGuard](https://github.com/gpartin/WaveGuardClient), a general-purpose anomaly detection engine that uses GPU-accelerated wave simulations instead of machine learning. Your token's feature vector is encoded onto a 3D lattice and evolved through coupled wave equations. Normal data produces stable wave patterns; anomalous data produces divergent ones. The advantage over statistical methods: WaveGuard captures non-linear interactions between features that simple threshold checks miss. This is why it flagged FTT 13 days before z-score analysis in backtesting. No model training, no drift, no retraining. Deterministic for the same input.
## Key Features (v0.6.0) - **Backtested**: 100% recall on 7 historical crashes with 27-day average lead time - **Free tier**: 5 calls/day per IP, no signup required - **2 payment options**: x402 USDC per-scan ($0.05) or RapidAPI plans - **Deterministic**: Same input always produces same verdict - **MCP server**: 7 tools for AI agent integration (stdio + HTTP) - **Python SDK**: `pip install CryptoGuardClient` with typed exceptions - **Physics Intelligence**: 7 endpoints for trend/regime/volatility/spectral/whale/momentum analysis - **Intel endpoints**: Premium validate-trade-plus ($0.10) and counterfactual-trade ($0.08) - **Contract resolution**: Accepts name, ticker, or contract address across 7 chains - **Batch validation**: Up to 20 trades or 50 tokens per call - **Rug pull detection**: DexScreener-powered liquidity and holder analysis - **30 REST endpoints**: Complete crypto risk intelligence API ## Pricing | Tier | Cost | Limit | Auth | |------|------|-------|------| | **Free** | $0 | 5 calls/day per IP | None | | **Per-scan** | $0.05/call | Unlimited | [x402](https://github.com/coinbase/x402) USDC micropayment | | **RapidAPI Basic** | $0/mo | 500K requests | [RapidAPI](https://rapidapi.com/) proxy key | | **RapidAPI Pro** | $9.99/mo | 10K requests | [RapidAPI](https://rapidapi.com/) proxy key | | **RapidAPI Ultra** | $29.99/mo | 100K requests | [RapidAPI](https://rapidapi.com/) proxy key | ## Architecture ``` AI Agent / User | v CryptoGuard API (Modal, stateless) |-- MCP endpoint (7 tools, JSON-RPC 2.0) |-- Auth: RapidAPI → API key → x402 (USDC) → Free tier |-- Token resolution (name/ticker/address → CoinGecko ID, 7 chains) |-- Market data (CoinGecko + DexScreener, cached) |-- Physics Intelligence (trend, regime, correlation, volatility, spectral, whale, momentum) |-- Intel (validate-trade-plus, counterfactual-trade) +-- WaveGuard anomaly engine (GPU-accelerated) ``` ## License MIT