Token RugCheck

March 22, 2026 · View on GitHub

We're LIVE on Mainnet! Try the interactive playground: https://rugcheck.aethercore.dev/playground

# Quick test — no setup needed
curl https://rugcheck.aethercore.dev/health

# Free tier (20 requests/day per IP, no payment needed)
curl https://rugcheck.aethercore.dev/v1/audit/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

# After free quota exhausted, see the 402 paywall
curl https://rugcheck.aethercore.dev/v1/audit/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

What you get: A three-layer safety audit for any Solana token — machine-readable verdict, LLM-friendly analysis, and raw evidence — all in one API call. 20 free requests/day per IP, then $0.02 USDC per request.

Disclaimer: Not financial advice (NFA). Token safety scores are automated heuristics — may be inaccurate or outdated. DYOR. The authors accept no liability for losses.

Live Demos (Mainnet)

All demos below are real mainnet transactions — left side is the client, right side is the production server logs.

1. Wallet Setup (ag402 setup)

https://github.com/user-attachments/assets/fb6b1ecb-8d42-43b7-9939-4751ca09b63f

2. Auditing a Safe Token (BONK — risk score 3, SAFE)

https://github.com/user-attachments/assets/4b3814ae-96af-496b-86b7-c80cddef1475

3. Auditing a Risky Token (TRUMP — risk score 60, HIGH)

https://github.com/user-attachments/assets/6e359374-8caf-41c7-8bd1-14f63eb6d6e8

How It Works

Your AI Agent                        RugCheck Service
     │                                      │
     │  GET /v1/audit/{mint}                │
     ├─────────────────────────────────────▶│
     │                                      │
     │  200 OK + Audit Report               │  ← Free tier (20/day per IP)
     │  X-Free-Remaining: 19                │
     │◀─────────────────────────────────────┤
     │                                      │
     │  ... after free quota exhausted ...  │
     │                                      │
     │  GET /v1/audit/{mint}                │
     ├─────────────────────────────────────▶│
     │                                      │
     │  402 Payment Required                │
     │  (pay 0.02 USDC on Solana)           │
     │◀─────────────────────────────────────┤
     │                                      │
     │  USDC payment (on-chain)             │
     ├─────────────────────────────────────▶│
     │                                      │
     │  200 OK + Audit Report               │
     │◀─────────────────────────────────────┤

Input a Solana token mint address → get a three-layer report:

Layer	For	Content
Action	Machines	`is_safe`, `risk_score` (0-100), `risk_level` (SAFE/LOW/MEDIUM/HIGH/CRITICAL)
Analysis	LLMs	Summary, red flags, green flags
Evidence	Humans	Price, liquidity, holder distribution, mint/freeze authority, raw data

Data sources: RugCheck.xyz + DexScreener + GoPlus Security (concurrent fetch, graceful degradation).

Try It Now (3 minutes)

Step 1: Install

pip install "ag402-core[crypto]" httpx

Step 2: Set up your wallet

ag402 setup
# Choose: Consumer → Mainnet
# Enter your Solana private key (encrypted locally with AES)
# Set safety limits (default: \$10/day max)

Step 3: Run an audit

# Python one-liner
python3 -c "
import asyncio, httpx, ag402_core
ag402_core.enable()
async def run():
    async with httpx.AsyncClient(timeout=30.0) as c:
        r = await c.get('https://rugcheck.aethercore.dev/v1/audit/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263')
        print(r.json()['action'])
asyncio.run(run())
"

Or in Python:

import asyncio, httpx, ag402_core

ag402_core.enable()  # Auto-handles 402 → pay → retry

async def check_token(mint: str):
    async with httpx.AsyncClient(timeout=30.0) as client:
        resp = await client.get(
            f"https://rugcheck.aethercore.dev/v1/audit/{mint}"
        )
        report = resp.json()
        action = report["action"]

        if not action["is_safe"]:
            print(f"DANGER — risk score {action['risk_score']}/100")
            for flag in report["analysis"]["red_flags"]:
                print(f"  🚩 {flag['message']}")
        else:
            print(f"SAFE — {report['analysis']['summary']}")

asyncio.run(check_token("DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"))

Requirements: Your wallet needs USDC (for payments) and a small amount of SOL (for transaction fees, ~0.01 SOL).

Command-line Audit Tool (`ag402 pay`)

You can audit any token directly from the command line using the ag402 CLI:

# Single request with auto-payment
ag402 pay https://rugcheck.aethercore.dev/v1/audit/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

# Or use the Python snippet above with a custom gateway

Note: mainnet_buyer_test.py (referenced in OPERATIONS.md history) is a local wallet test script intentionally excluded from the repo via .gitignore — it contains wallet-specific configuration not suitable for distribution.

API Reference

Base URL: https://rugcheck.aethercore.dev

Endpoints

Method	Path	Auth	Description
GET	`/v1/audit/{mint_address}`	USDC payment	Full safety audit report
GET	`/v1/trending`	None	Trending tokens from DexScreener
GET	`/playground`	None	Interactive web UI — audit tokens in the browser
GET	`/health`	None	Service health + upstream status
GET	`/stats`	Loopback only	Request counts + cache hit rate
GET	`/metrics`	Loopback only	Prometheus metrics
GET	`/audit/{mint_address}`	USDC payment	Deprecated — use `/v1/`

Audit Response Schema

{
  "contract_address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "chain": "solana",
  "audit_timestamp": "2026-03-08T12:34:56.789012+00:00",
  "degraded": false,
  "action": {
    "is_safe": true,
    "risk_level": "SAFE",
    "risk_score": 3
  },
  "analysis": {
    "summary": "No significant risk signals detected. Always do your own research (DYOR).",
    "red_flags": [
      {"level": "LOW", "message": "Token metadata is mutable — common for Solana tokens."}
    ],
    "green_flags": [
      {"message": "Mint authority renounced (Mint Renounced)."},
      {"message": "Liquidity pool is sufficiently protected (LP Burned or Locked)."},
      {"message": "No freeze authority (Not Freezable)."}
    ]
  },
  "evidence": {
    "token_name": "Bonk",
    "token_symbol": "Bonk",
    "price_usd": 0.00012,
    "liquidity_usd": 85000000.0,
    "is_mintable": false
  },
  "metadata": {
    "data_sources": ["RugCheck", "DexScreener", "GoPlus"],
    "data_completeness": "full",
    "cache_hit": false,
    "data_age_seconds": 0,
    "response_time_ms": 738,
    "disclaimer": "This report is generated by automated data aggregation. Not financial advice (NFA)."
  }
}

Key Fields

Field	Type	Description
`action.is_safe`	`bool`	Machine-readable verdict
`action.risk_score`	`int`	0 (safest) to 100 (most dangerous)
`action.risk_level`	`string`	`SAFE` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL`
`degraded`	`bool`	`true` if upstream sources failed — treat with extra caution
`metadata.data_completeness`	`string`	`full` / `partial` / `minimal` / `unavailable`
`metadata.data_age_seconds`	`int\|null`	`0` = fresh, `>0` = cached

Health Check

# Development mode — detailed info
GET /health → {"status": "ok", "service": "token-rugcheck-mcp", "version": "0.1.0"}

# Production mode (RUGCHECK_PRODUCTION=true) — minimal, no internal details
GET /health → {"status": "ok"}

`status`	Meaning
`ok`	All systems normal
`degraded`	Upstream API failures — service continues with available data

Deployment Guide (Self-hosting)

Automated Deployment: See OPERATIONS.md for one-click scripts and ops runbook.

Architecture

Client (AI Agent)
  │ HTTPS
  ▼
Cloudflare (SSL termination, DDoS protection)
  │ HTTP:80
  ▼
┌─────────────────────────────────────────────────┐
│  Docker Compose                                 │
│  ┌──────────────────────┐  ┌──────────────────┐ │
│  │ ag402-gateway :80    │  │ rugcheck-audit   │ │
│  │ (QuotaAwareGateway)  │  │ :8000 (internal) │ │
│  │                      │  │ Audit engine     │ │
│  │  free quota left?    │  │                  │ │
│  │  ├─ yes → HTTP proxy─┼─▶│                  │ │
│  │  └─ no  → 402 pay   │  │                  │ │
│  └──────────────────────┘  └──────────────────┘ │
└─────────────────────────────────────────────────┘

Three Environments

Environment	Blockchain	Real Funds	Use Case
Test (mock)	None	No	Local dev, CI
Devnet	Solana Devnet	No (faucet)	Integration testing
Production	Solana Mainnet	Yes	Live service

Quick Start — Test Mode (zero config)

pip install -e .
python -m rugcheck.main &          # Audit server on :8000
python -m rugcheck.gateway &       # Gateway on :8001 (mock payments)
curl http://localhost:8001/v1/audit/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

Quick Start — Production (Docker)

# 1. One-click deploy to your server
bash scripts/deploy-oneclick.sh

# Or manually:
cp .env.example .env               # Edit with your wallet address + keys
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Provider `.env` (Production)

X402_MODE=production
X402_NETWORK=mainnet
AG402_ADDRESS=<your_solana_wallet>  # Receives USDC payments
AG402_PRICE=0.02                    # USDC per audit
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com  # Read-only RPC for payment verification
RUGCHECK_PRODUCTION=true            # Disable /docs, harden /health response
UVLOOP_INSTALL=0                    # Required: prevents uvloop/aiosqlite crash

# Optional: prepaid fast-path (~1ms per request instead of ~500ms)
# Generate: python -c "import secrets; print(secrets.token_hex(32))"
AG402_PREPAID_SIGNING_KEY=<random_32+_char_key>

# Optional: higher GoPlus rate limits
GOPLUS_APP_KEY=<key>
GOPLUS_APP_SECRET=<secret>

Note: As a seller/provider, you do not need SOLANA_PRIVATE_KEY. The gateway verifies buyer payments via read-only RPC — no signing required.

Consumer Setup

pip install "ag402-core[crypto]" httpx
ag402 setup                         # Interactive wizard
ag402 status                        # Verify wallet + balance

import ag402_core
ag402_core.enable()
# Now all httpx requests auto-handle 402 → pay → retry

Configuration Reference

Service

Variable	Default	Description
`RUGCHECK_HOST`	`0.0.0.0`	Bind address
`RUGCHECK_PORT`	`8000`	Bind port
`RUGCHECK_LOG_LEVEL`	`info`	`debug` / `info` / `warning` / `error`
`RUGCHECK_PRODUCTION`	`false`	`true` disables `/docs`, `/redoc`, `/openapi.json`
`UVICORN_WORKERS`	`1`	Worker processes
`CACHE_TTL_SECONDS`	`3`	Cache TTL (short to catch rug pulls)
`CACHE_MAX_SIZE`	`5000`	Max cached entries (LRU)
`FREE_DAILY_QUOTA`	`20`	Free requests per IP per day
`FREE_QUOTA_ENABLED`	`true`	Enable/disable the free tier in the gateway
`PAID_RATE_LIMIT`	`120`	Paid requests per IP per minute

Upstream APIs

Variable	Default	Description
`DEXSCREENER_TIMEOUT_SECONDS`	`1.5`	DexScreener timeout
`GOPLUS_TIMEOUT_SECONDS`	`2.5`	GoPlus timeout
`RUGCHECK_API_TIMEOUT_SECONDS`	`3.5`	RugCheck timeout
`GOPLUS_APP_KEY`	—	GoPlus API key (optional)
`GOPLUS_APP_SECRET`	—	GoPlus API secret

ag402 Payment

Variable	Default	Description
`AG402_PRICE`	`0.02`	USDC per request
`AG402_ADDRESS`	—	Provider wallet (receives payments)
`AG402_GATEWAY_PORT`	`8001`	Gateway port
`AG402_PREPAID_SIGNING_KEY`	—	HMAC signing key for prepaid fast-path (optional, `>=32` chars)
`X402_MODE`	`test`	`test` (mock) / `production` (real)
`X402_NETWORK`	`devnet`	`mock` / `devnet` / `mainnet`
`SOLANA_RPC_URL`	`https://api.devnet.solana.com`	Read-only Solana RPC for payment verification

Consumer Safety Limits

Variable	Default	Description
`X402_DAILY_LIMIT`	`10.0`	Max daily spend (USD)
`X402_SINGLE_TX_LIMIT`	`5.0`	Max per-transaction
`X402_PER_MINUTE_LIMIT`	`2.0`	Max spend per minute
`X402_PER_MINUTE_COUNT`	`5`	Max transactions per minute

ag402 CLI Reference

ag402 setup                  # Interactive setup wizard
ag402 status                 # Dashboard: mode, wallet, balance
ag402 balance                # Check SOL + USDC balance
ag402 doctor                 # Diagnose environment issues
ag402 history --limit 10     # Recent transactions
ag402 pay <url>              # Send a single paid request
ag402 demo                   # Quick E2E test (mock mode)
ag402 demo --devnet          # E2E test with Devnet transactions
ag402 info                   # Protocol version

# Prepaid packages (v0.1.15+) — pre-purchase call bundles for ~1ms per request
ag402 prepaid buy <gateway_url> <package_id>  # Purchase a prepaid package
ag402 prepaid status                          # List all credentials + remaining calls
ag402 prepaid purge                           # Remove expired/depleted credentials
ag402 prepaid pending                         # Show in-flight purchase (if any)
ag402 prepaid recover <gateway_url>           # Recover credential after timeout/network failure

Development

pip install -e ".[dev]"
python -m pytest tests/ -v              # 153 tests
ruff check src/ tests/                  # Lint
python examples/demo_agent.py           # E2E demo (direct)
python examples/demo_agent.py --with-gateway  # E2E demo (with payment)

Project Structure

src/rugcheck/
├── config.py              # Environment-based configuration
├── models.py              # Pydantic models (report schema)
├── cache.py               # Async-safe TTL cache (LRU, asyncio.Lock)
├── quota.py               # Shared quota & IP resolution (DailyQuota, resolve_client_ip)
├── server.py              # FastAPI app + rate limiter + health checks
├── main.py                # Audit server entry point
├── gateway.py             # ag402 gateway entry point
├── gateway_wrapper.py     # QuotaAwareGateway — free-tier bypass + HTTP proxy
├── fetchers/
│   ├── base.py            # BaseFetcher ABC
│   ├── goplus.py          # GoPlus Security API
│   ├── rugcheck.py        # RugCheck.xyz API
│   ├── dexscreener.py     # DexScreener API
│   └── aggregator.py      # Concurrent fetch + merge
└── engine/
    └── risk_engine.py     # Deterministic rule-based scoring

Security

Free-tier gateway — 20/day per IP with X-Free-Remaining header; quota-exhausted → 402
Rate limiting — free: 20/day per IP; paid: 120/min per IP
Trusted proxy model — CF-Connecting-IP only trusted from Cloudflare IPs; IPv6 normalized
Header stripping — proxy/hop-by-hop headers stripped before forwarding (anti-spoofing)
Production hardening — /docs, /redoc, /openapi.json disabled
Gateway fail-safe — refuses to start if payment verifier fails in production
Graceful degradation — free-tier proxy failure falls through to 402 payment path
CSP-hardened playground — zero inline event handlers, all user data escaped, whitelist-validated CSS injection points
Cache isolation — deep-copy on get/set prevents shared state corruption
Degraded short-TTL — incomplete reports cached only 10s
Prometheus path normalization — prevents cardinality explosion
Upstream protection — Semaphore(20) + max_connections=50
Error sanitization — never exposes internal paths

Troubleshooting

Problem	Cause	Fix
`402 Payment Required`	Free daily quota exhausted (check `X-Free-Remaining` header)	Wait for UTC midnight reset, or use `ag402_core.enable()` / `ag402 pay <url>` for paid access
`InsufficientFundsForRent`	Wallet SOL too low for ATA creation	Send ≥ 0.01 SOL to your wallet
`Payment not confirmed on-chain` (403)	Solana network confirmation timeout	Retry — transient network issue
`ValueError: Production mode requires PaymentVerifier`	Missing crypto deps	`pip install -e ".[crypto]"`
`ImportError: solana/solders`	Missing crypto deps	`pip install "ag402-core[crypto]"`
Gateway keeps restarting	Missing `SOLANA_PRIVATE_KEY` or `AG402_ADDRESS`	Check `.env` configuration
Health returns `degraded`	Upstream APIs failing	Service continues with available sources — check `/health`

License

MIT