Solana Rug Guard $RUG

Docs: https://graphtheory.xyz/solana-rug/

13-factor on-chain rug-pull detection for Solana tokens and wallets. No paid APIs. No registration. Just a Python script and a Hermes skill.

Run it as a one-shot CLI against any mint or wallet. Or install it as a Hermes Agent skill and ask in natural language: "Hey Hermes, is this token safe?" Every check is deterministic — the same input always produces the same score, with a full breakdown of why.

---

Install & Get Started

Prerequisites

• Python 3.11+
• Hermes Agent (optional — the CLI works standalone)
• No API keys. The tool uses public Solana RPCs and the free DexScreener API.

Always install from a trusted source. Official packages are published to

PyPI and

GitHub Releases.

The source is a single auditable Python file — no compiled binaries, no

opaque dependencies. You can verify the checksums on the GitHub Releases page

and compare against the source in this repo.

Option A: Install as a Hermes Skill (recommended)

# From the Hermes Agent repo:
hermes skills install official/blockchain/solana-rug
Or from a local checkout:
cd optional-skills/blockchain/solana-rug/
hermes skills install ./SKILL.md

Then ask in natural language:

"Is token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 safe?"
"Rug-check F4J5LKyEQraMem8nspPAzwHXaaKMMDsxyt7GUK94pump"
"Scan wallet 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM for risky tokens"

Option B: Run the CLI Standalone

# Single file — no install needed (from GitHub Releases)
curl -OL https://github.com/rugpullnet/solana-rug/releases/latest/download/rugguard.py
python3 rugguard.py token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --md

# Or clone the repo
git clone https://github.com/rugpullnet/solana-rug.git
cd solana-rug
python3 scripts/rugguard.py --help

# Or pip install from PyPI (trusted source)
pip install solana-rug
solana-rug token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

Verify It Works

python3 rugguard.py token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --json

Expected: BONK returns safety_score: 100, zero warnings, market data showing $682k liquidity on Meteora.

---

How to Use

Token Analysis

# JSON output (default) — pipe through jq
python3 rugguard.py token <MINT_ADDRESS>
Human-readable Markdown report
python3 rugguard.py token <MINT_ADDRESS> --md
Full example
python3 rugguard.py token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --md

JSON output includes a market_data block with DexScreener enrichment:

{
  "safety_score": 100,
  "risk_level": "LOW",
  "flags": {
    "mintauthorityactive": false,
    "freezeauthorityactive": false,
    "sniper_detected": false,
    "suspicious_name": false,
    "subpennyprice": false,
    "deployercancrash_price": false
  },
  "market_data": {
    "dex": "meteora",
    "liquidity_usd": 682156.92,
    "volume_24h": 936.68,
    "price_usd": 0.000004892,
    "pricechange24h": -2.92,
    "txns_24h": 212
  }
}

Wallet Scan

python3 rugguard.py wallet <ADDRESS>

Scans all SPL tokens held by a wallet. For each token with meaningful balance, checks mint authority. Returns a prioritized list of risky tokens ordered by safety score (lowest first).

Watch Mode, History, and Webhooks

# One check, store a SQLite history row, then exit
python3 rugguard.py watch <MINT_ADDRESS> --iterations 1
Continuous monitoring every 60 seconds
python3 rugguard.py watch <MINT_ADDRESS> --interval 60
Alert whenever score/flags/warnings change, or whenever safety <= 70
python3 rugguard.py watch <MINT_ADDRESS> --threshold 70 --webhook https://example.com/webhook

Watch mode stores every run in a local SQLite database and prints one JSON event per check:

{
  "mint": "...",
  "safety_score": 79,
  "risk_level": "LOW",
  "changed": true,
  "reasons": ["score changed 82 -> 79"],
  "history_db": "~/.solana-rug/history.sqlite3"
}

Webhook payloads use the same JSON event shape and are sent only when a change/threshold alert fires.

Environment

| Variable | Default | Description | |----------|---------|-------------| | SOLANARPCURL | https://api.mainnet-beta.solana.com | Override RPC endpoint. Set to a private node (Helius, QuickNode) for production reliability. | | SOLANARUGHISTORY_DB | ~/.solana-rug/history.sqlite3 | SQLite path for watch-mode score history. | | SOLANARUGWEBHOOK_URL | empty | Optional webhook URL for watch-mode alerts. | | SOLANARUGWATCH_INTERVAL | 60 | Default watch interval in seconds. | | SOLANARUGHISTORYRETENTIONDAYS | 90 | Auto-prune history entries older than this many days. | | SOLANARUGLIQTHRESHOLDCRITICAL | 1000 | Liquidity below this USD amount is scored as critical risk (5pts). | | SOLANARUGLIQTHRESHOLDHIGH | 5000 | Liquidity below this is scored as high risk (4pts). | | SOLANARUGLIQTHRESHOLDMEDIUM | 20000 | Liquidity below this is scored as medium risk (3pts). | | SOLANARUGLIQTHRESHOLDLOW | 100000 | Liquidity below this is scored as low risk (1pt). | | SOLANARUGLIQVOLRATIO_WARNING | 15 | Volume/liquidity ratio above this triggers a wash-trading warning (+3pts). | | SOLANARUGLIQVOLRATIO_MIN | 0.05 | Volume/liquidity ratio below this flags an inactive/dead pool (+3pts). | | WALLETSCANWORKERS | 4 | Max concurrency limit for wallet token scanning (max 10). |

---

Architecture

Data Flow

User Input (mint address)
        │
        ▼
┌─────────────────────┐
│  fetchtokenmeta   │──► Solana RPC: getAccountInfo (jsonParsed)
│  (on-chain data)    │──► Token-2022 extension detection
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  check_authorities  │──► Mint authority, freeze authority, token program
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  fetchtokenholders│──► RPC: getTokenLargestAccounts
│                     │──► Falls back to DexScreener tx-count estimates
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  detect_liquidity   │──► RPC: getProgramAccounts (Raydium, pumpSwap, Orca)
│                     │──► Falls back to DexScreener for pool data
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  checksniperpat.  │──► First 15 mint signatures → rapid-buy detection
│  estimatetokenage │──► Signature pagination + DexScreener fallback
│  check_suspicious   │──► Name/symbol keyword blacklist
│  check_honeypot     │──► Jupiter quote API (optional check)
│  computedumprisk  │──► Deployer % vs pool liquidity
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  DexScreener enrich │──► Price, volume, liquidity, 24h change, tx count
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Scoring Engine     │──► 13 risk factors → 0-100 safety score
│  + Markdown/JSON    │──► Human-readable report or structured data
└─────────────────────┘

Directory Layout

solana-rug/
├── SKILL.md                    # Hermes skill definition (docs all 13 checks)
├── scripts/
│   └── rugguard.py            # Core engine (~1470 lines, stdlib-only)
├── solana_rug/                 # PyPI package wrapper
│   ├── init.py
│   └── py.typed
├── pyproject.toml
├── tests/
│   └── test_checks.py         # 20 tests (13 unit + 7 blockchain integration)
├── README.md
├── CONTRIBUTING.md
└── LICENSE                     # MIT

The 13 Risk Factors

Each factor contributes zero or more points to the total risk score. Higher total risk = lower safety score.

| # | Factor | Max | What It Catches | Data Source | |---|--------|:---:|-----------------|-------------| | 1 | Mint Authority | 15 | Dev can print unlimited new tokens | RPC | | 2 | Freeze Authority | 5 | Dev can freeze accounts | RPC | | 3 | LP Locked/Burned | 15 | LP tokens can be pulled, no pool exists | RPC + DexScreener | | 4 | Liquidity Size | 5 | Pool under $20k → high price impact | DexScreener | | 5 | Holder Concentration | 10 | Top 10 wallets own >50% of supply | RPC + DexScreener | | 6 | Dev Risk | 5 | Dev holds >15% of supply | RPC | | 7 | Token Age | 5 | Under 7 days old → statistically riskier | DexScreener | | 8 | Mint History | 5 | Dev minted more tokens after launch | RPC | | 9 | Honeypot | 10 | Sell simulation fails | Jupiter API | | 10 | Sniper Bots | 10 | Bots bought within first 20 seconds | RPC sig analysis | | 11 | Suspicious Name | 5 | Name contains "rug", "scam", "ponzi", etc. | On-chain + DexScreener | | 12 | Sub-Penny Price | 5 | Price < $0.0001 on a young or thin token | DexScreener | | 13 | Deployer Dump Risk | 5 | Dev could crash price by selling | DexScreener + RPC |

How Risks Are Scored

Each check is independent and deterministic. The total risk sum has no upper cap — a token with every flag maxed out scores 0/100. The 13 factors are split across:

• 3 on-chain structural checks (mint authority, freeze authority, LP locked/burned) — the classic rug vectors
• 4 market-health checks (liquidity size, holder concentration, age, mint history) — sustainability signals
• 3 behavioral checks (honeypot, snipers, name stigma) — adversarial pattern detection
• 3 position checks (dev risk, sub-penny price, deployer dump risk) — who holds what and what that means

Score bands:

| Score | Risk | Meaning | |:-----:|:----:|---------| | 80-100 | LOW | On-chain mechanics clean. Standard DeFi risks only. | | 50-79 | MEDIUM | Some risk factors present. Review flagged warnings. | | 20-49 | HIGH | Multiple red flags. Likely a risky token. | | 0-19 | CRITICAL | Strong evidence of malicious setup. |

Data Sources (in order of preference)

• Solana public RPC — Mint accounts, token holders, signatures, program accounts. Retries across 4 public endpoints with round-robin fallback.
• DexScreener API — Real pool data when getProgramAccounts is rate-limited. Provides price, liquidity, volume, pair info, and creation time.
• Jupiter quote API — Optional honeypot check. Simulates a buy/sell to detect trade restrictions.

All calls are cached in-memory with a 5-minute TTL to avoid redundant network requests.

---

Support

Solana Rug Guard is free, open-source MIT software. No paywalls, no API keys, no registration.

If the tool saved you from a bad trade or helped you understand what happened to a coin you created, consider supporting the project by grabbing a small bag of $RUG on PumpSwap.

Token: F4J5LKyEQraMem8nspPAzwHXaaKMMDsxyt7GUK94pump
DEX:   pumpSwap (RUG/SOL pair)

Or check the current chart on DexScreener:

https://dexscreener.com/solana/4sHKYieWsGtrmtqjdXPRzSdVywXZ1jUQGbM8QbkBXMB9

Every buy adds liquidity to the pool and helps keep this project sustainable.

---

MIT License · Built for Hermes Agent · No paid APIs required