Token RugCheck — Solana Token Safety Audit for AI Agents

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)

setup_github.mp4

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

safe_github.mp4

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

risk_github.mp4

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Token RugCheck — Solana Token Safety Audit for AI Agents

Live Demos (Mainnet)

How It Works

Try It Now (3 minutes)

Step 1: Install

Step 2: Set up your wallet

Step 3: Run an audit

Command-line Audit Tool (`ag402 pay`)

API Reference

Endpoints

Audit Response Schema

Key Fields

Health Check

Deployment Guide (Self-hosting)

Architecture

Three Environments

Quick Start — Test Mode (zero config)

Quick Start — Production (Docker)

Provider `.env` (Production)

Consumer Setup

Configuration Reference

Service

Upstream APIs

ag402 Payment

Consumer Safety Limits

ag402 CLI Reference

Development

Project Structure

Security

Troubleshooting

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Token RugCheck — Solana Token Safety Audit for AI Agents

Live Demos (Mainnet)

How It Works

Try It Now (3 minutes)

Step 1: Install

Step 2: Set up your wallet

Step 3: Run an audit

Command-line Audit Tool (ag402 pay)

API Reference

Endpoints

Audit Response Schema

Key Fields

Health Check

Deployment Guide (Self-hosting)

Architecture

Three Environments

Quick Start — Test Mode (zero config)

Quick Start — Production (Docker)

Provider .env (Production)

Consumer Setup

Configuration Reference

Service

Upstream APIs

ag402 Payment

Consumer Safety Limits

ag402 CLI Reference

Development

Project Structure

Security

Troubleshooting

License

Command-line Audit Tool (`ag402 pay`)

Provider `.env` (Production)