Metadata-Version: 2.4
Name: solana-rug
Version: 0.1.0
Summary: On-chain rug-pull detection for Solana tokens — Safety Score 0-100, zero paid APIs required.
Author: Hermes Agent / Solana Rug Guard
License: MIT License
        
        Copyright (c) 2025 Hermes Agent / Solana Rug Guard
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/NousResearch/hermes-agent/tree/main/optional-skills/blockchain/solana-rug
Project-URL: Repository, https://github.com/NousResearch/hermes-agent
Project-URL: Bug Tracker, https://github.com/NousResearch/hermes-agent/issues
Keywords: solana,rug-check,blockchain,security,defi,crypto
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Solana Rug Guard

[![CI](https://github.com/rugpullnet/solana-rug/actions/workflows/ci.yml/badge.svg)](https://github.com/rugpullnet/solana-rug/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**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](https://hermes-agent.nousresearch.com) (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](https://pypi.org/project/solana-rug/) and
> [GitHub Releases](https://github.com/rugpullnet/solana-rug/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)

```bash
# 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:

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

### Option B: Run the CLI Standalone

```bash
# 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
```

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

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

### Verify It Works

```bash
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

```bash
# 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:

```json
{
  "safety_score": 100,
  "risk_level": "LOW",
  "flags": {
    "mint_authority_active": false,
    "freeze_authority_active": false,
    "sniper_detected": false,
    "suspicious_name": false,
    "sub_penny_price": false,
    "deployer_can_crash_price": false
  },
  "market_data": {
    "dex": "meteora",
    "liquidity_usd": 682156.92,
    "volume_24h": 936.68,
    "price_usd": 0.000004892,
    "price_change_24h": -2.92,
    "txns_24h": 212
  }
}
```

### Wallet Scan

```bash
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).

### Environment

| Variable | Default | Description |
|----------|---------|-------------|
| `SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Override RPC endpoint. Set to a private node (Helius, QuickNode) for production reliability. |

---

## Architecture

### Data Flow

```
User Input (mint address)
        │
        ▼
┌─────────────────────┐
│  fetch_token_meta   │──► Solana RPC: getAccountInfo (jsonParsed)
│  (on-chain data)    │──► Token-2022 extension detection
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  check_authorities  │──► Mint authority, freeze authority, token program
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  fetch_token_holders│──► RPC: getTokenLargestAccounts
│                     │──► Falls back to DexScreener tx-count estimates
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  detect_liquidity   │──► RPC: getProgramAccounts (Raydium, pumpSwap, Orca)
│                     │──► Falls back to DexScreener for pool data
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  check_sniper_pat.  │──► First 15 mint signatures → rapid-buy detection
│  estimate_token_age │──► Signature pagination + DexScreener fallback
│  check_suspicious   │──► Name/symbol keyword blacklist
│  check_honeypot     │──► Jupiter quote API (optional check)
│  compute_dump_risk  │──► 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)

1. **Solana public RPC** — Mint accounts, token holders, signatures, program accounts. Retries across 4 public endpoints with round-robin fallback.
2. **DexScreener API** — Real pool data when `getProgramAccounts` is rate-limited. Provides price, liquidity, volume, pair info, and creation time.
3. **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*
