Chronolapse411/sicarius-guard

Solana Token & NFT Safety Oracle for AI Agents & Trading Bots

GitHub stars npm version npm downloads License: MIT

sicarius-guard MCP server Score Smithery

Real-time token and NFT safety analysis combining byte-level on-chain inspection, LP lock verification, deployer reputation scoring, market intelligence, and NFT fraud detection. Built for autonomous AI agents, MCP-enabled LLMs, and trading infrastructure.

"Don't trade blind. Query SicariusGuard before every swap."

🌐 Live API: https://sicarius-guard-640545264957.us-east4.run.app

# Try it now — no auth required (100 free calls/day)
curl https://sicarius-guard-640545264957.us-east4.run.app/v1/scan/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

---

📑 Table of Contents

• What It Does
• Quick Start
• API Endpoints
• MCP Server (for AI Agents)
• Architecture
• x402 Payment Protocol
• Configuration
• Performance
• Tech Stack
• Why SicariusGuard?
• Related MCP Servers
• Links

🔍 What It Does

SicariusGuard performs 12 layers of safety analysis on any Solana SPL token or NFT:

On-Chain Safety (Layers 1-5)

Layer	Source	Detection
🔓 Mint Authority	Raw SPL mint bytes	Can deployer print infinite tokens?
🧊 Freeze Authority	SPL layout offset 46	Can deployer freeze any wallet?
⚠️ Token-2022 Extensions	Extension type scan	PermanentDelegate, TransferHook, ConfidentialTransfers
🍯 Honeypot Detection	Jupiter sell simulation	Can you actually sell this token?
📊 Holder Concentration	getTokenLargestAccounts	Top 5 wallets controlling >50% supply?

LP & Token Maturity (Layers 6-8)

Layer	Source	Detection
🔒 LP Lock/Burn	Raydium V4 byte decode + GeckoTerminal	Is liquidity locked, burned, or unlocked?
⏰ Token Age	Helius enhanced RPC	Newborn (<24h)? Young (<7d)? Mature?
⚖️ Unified Scoring	5-axis weighted engine	Combined risk across all layers

Intelligence & Reputation (Layers 9-12)

Layer	Source	Detection
📈 Market Intel	Birdeye API	Liquidity, volume, wash trading, manipulation
🔎 Wallet Reputation	Helius Identity + Funded-By	Is the deployer a known scammer?
🕵️ Deployer Recon	DAS + Enhanced TX	Serial rugger? Burner wallet? Dead token history?
🖼️ NFT Intelligence	Helius DAS + Magic Eden	Counterfeit collection? Unverified creators? Pricing anomaly?

5-Axis Weighted Risk Scoring

finalScore = (onChain × 0.45) + (lpLock × 0.15) + (age × 0.05) + (market × 0.22) + (reputation × 0.13)

0       → SAFE
1-15    → CAUTION
16-50   → HIGH_RISK
51-100  → CRITICAL

Weight	Source	What It Catches
45%	On-chain safety	Mint/freeze authority, honeypots, extensions, supply
15%	LP lock analysis	Unlocked liquidity, unburned LP tokens, lock duration
5%	Token age	Newborn tokens (<24h), recently deployed
22%	Birdeye market data	Low liquidity, wash trading, price manipulation
13%	Helius wallet intel	Scammer wallets, suspicious funding chains, burner deployers

🚀 Quick Start

# Clone
git clone https://github.com/Chronolapse411/sicarius-guard.git
cd sicarius-guard

# Install
npm install

# Configure
cp .env.example .env
# Add your HELIUS_RPC_URL and optionally BIRDEYE_API_KEY

# Build & Run
npm run build
npm start

📡 API Endpoints

REST API (Port 3400)

Method	Endpoint	Description
POST	/v1/check	Full on-chain safety analysis
GET	/v1/check/:mint	Convenience GET for safety check
POST	/v1/scan	Full 12-layer analysis + Birdeye + Helius + deployer recon
GET	/v1/scan/:mint	Convenience GET for enriched scan
POST	/v1/honeypot	Honeypot-only check (Jupiter sell sim)
POST	/v1/holders	Holder concentration analysis
GET	/v1/lp-lock/:mint	LP lock/burn status for a token
GET	/v1/token-age/:mint	Token creation date and age category
GET	/v1/deployer/:address	Deployer reconnaissance dossier
GET	/v1/nft-check/:mint	NFT safety analysis (Magic Eden + Helius DAS)
GET	/v1/pricing	x402 payment pricing table
GET	/health	Service health check with cache stats

Example Request

# Basic safety check (BONK)
curl https://sicarius-guard-640545264957.us-east4.run.app/v1/check/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

# Full 12-layer scan
curl https://sicarius-guard-640545264957.us-east4.run.app/v1/scan/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

# LP lock check (POPCAT — 99.2% burned, 20,865 SOL liquidity)
curl https://sicarius-guard-640545264957.us-east4.run.app/v1/lp-lock/7GCihgDB8fe6LNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr

# NFT safety check (Mad Lads #7541)
curl https://sicarius-guard-640545264957.us-east4.run.app/v1/nft-check/7zuR45WCsAsWsrqvYPyvLXFiCRKuvjh7HrMcNJ6F36Kd

# Deployer recon (checks if a wallet is a serial scammer)
curl https://sicarius-guard-640545264957.us-east4.run.app/v1/deployer/BGkkEeg4Gj8VcoerFb2RephZNkTEfHmzJBZMv4S7qVTQ

Example Response (/v1/scan)

{
  "safety": {
    "safe": true,
    "riskScore": 0,
    "verdict": "SAFE",
    "checks": {
      "mintAuthority": { "status": "REVOKED", "safe": true },
      "freezeAuthority": { "status": "REVOKED", "safe": true },
      "token2022Extensions": { "status": "CLEAN", "safe": true },
      "supplyConcentration": { "status": "OK", "safe": true }
    }
  },
  "honeypot": { "isHoneypot": false, "sellable": true },
  "holders": { "concentrated": false, "stats": { "top10Pct": 8.2 } },
  "lpLock": {
    "status": "burned",
    "burnPct": 99.2,
    "liquiditySOL": 20865,
    "poolCreatedAt": "2023-12-12T..."
  },
  "tokenAge": {
    "ageCategory": "mature",
    "createdAt": "2022-12-08T...",
    "ageDays": 1259
  },
  "deployerRecon": {
    "verdict": "CLEAN",
    "recidivismScore": 0,
    "portfolioSize": 1
  },
  "combined": {
    "safe": true,
    "finalScore": 0,
    "verdict": "SAFE",
    "summary": "All checks passed — token appears safe"
  }
}

🤖 MCP Server (for AI Agents)

SicariusGuard exposes tools via the Model Context Protocol (MCP), enabling LLMs and agent frameworks to call safety checks natively.

Available MCP Tools (11)

Tool	Description	Read-Only
check_token_safety	5-layer on-chain rug pull, honeypot, and holder analysis	✅
check_honeypot	Jupiter DEX sell simulation — zero cost, quote-only	✅
check_holder_concentration	Top holder distribution analysis with concentration flags	✅
check_lp_lock	LP lock/burn status — Raydium V4 byte decode + burn detection	✅
check_token_age	Token creation date and age category via Helius RPC	✅
full_token_scan	12-layer scan: on-chain + LP + age + market + reputation + deployer	✅
get_wallet_reputation	Helius DAS identity, funding chain, deployer age analysis	✅
get_market_intel	Birdeye market data: price, volume, liquidity, risk flags	✅
recon_deployer	Deployer reconnaissance — portfolio health, serial scammer detection	✅
check_nft	NFT safety analysis — collection verification, floor price, risk scoring	✅
batch_scan	Parallel 12-layer scan of up to 10 tokens per call	✅

Install via npx (Recommended)

# Run directly — no cloning required
npx sicarius-guard

Install in Claude Code

claude mcp add sicarius-guard -- npx -y sicarius-guard

Install in Cursor

Install MCP Server

Or manually add to your Cursor MCP config:

{
  "mcpServers": {
    "sicarius-guard": {
      "command": "npx",
      "args": ["-y", "sicarius-guard"],
      "env": {
        "HELIUS_RPC_URL": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",
        "BIRDEYE_API_KEY": "your-birdeye-key"
      }
    }
  }
}

Install in VS Code

Or via CLI:

code --add-mcp '{"name":"sicarius-guard","command":"npx","args":["-y","sicarius-guard"]}'

Install from Source (Claude Desktop / Cursor)

{
  "mcpServers": {
    "sicarius-guard": {
      "command": "node",
      "args": ["dist/mcp-server.js"],
      "cwd": "/path/to/sicarius-guard",
      "env": {
        "HELIUS_RPC_URL": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",
        "BIRDEYE_API_KEY": "your-birdeye-key"
      }
    }
  }
}

🏗️ Architecture

┌──────────────────────────────────────────────────────────────┐
│                       SicariusGuard v1.1                      │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────────┐ │
│  │ REST API    │  │ MCP Server  │  │ x402 Payment Gate    │ │
│  │ Express 5   │  │ 11 tools    │  │ SOL Micropayments    │ │
│  │ 12 endpts   │  │ stdio       │  │                      │ │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬───────────┘ │
│         │                │                     │             │
│  ┌──────▼────────────────▼─────────────────────▼───────────┐ │
│  │               12-Layer Analysis Engine                   │ │
│  │                                                          │ │
│  │  token_safety.ts   ┐                                    │ │
│  │  honeypot_sim.ts   ├─ On-Chain (45%)                    │ │
│  │  holder_analysis.ts┘                                    │ │
│  │  lp_lock.ts          LP Lock  (15%)                     │ │
│  │  token_age.ts        Age      (5%)                      │ │
│  │  birdeye.ts          Market   (22%)                     │ │
│  │  helius_wallet.ts    Rep      (13%)                     │ │
│  │  scoring.ts          Unified 5-Axis Engine              │ │
│  │  deployer_recon.ts   Deployer Reconnaissance            │ │
│  │  nft_intel.ts        NFT Intelligence (ME + DAS)        │ │
│  └──────────────────────────┬───────────────────────────────┘ │
│                             │                                 │
│     ┌───────────┬───────────┼───────────┬─────────────┐      │
│     ▼           ▼           ▼           ▼             ▼      │
│  ┌───────┐ ┌─────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐ │
│  │Solana │ │Birdeye  │ │Helius  │ │Magic Eden│ │Gecko    │ │
│  │RPC    │ │API v3   │ │DAS+RPC │ │v2 (free) │ │Terminal │ │
│  └───────┘ └─────────┘ └────────┘ └──────────┘ └─────────┘ │
└──────────────────────────────────────────────────────────────┘

💰 x402 Payment Protocol

SicariusGuard implements the x402 HTTP Payment Required protocol for machine-native micropayments. AI agents can pay per API call with SOL — no registration, no API keys, no accounts.

How It Works

1. Agent hits /v1/scan → gets 402 + payment instructions
2. Agent sends SOL to treasury wallet
3. Agent retries with X-PAYMENT: <tx_signature>
4. Server verifies on-chain → returns safety data

Pricing

Endpoint	Price (SOL)	Description
/v1/check	0.001	On-chain safety check
/v1/scan	0.002	Full 12-layer scan
/v1/honeypot	0.0005	Honeypot simulation
/v1/holders	0.0005	Holder analysis
/v1/nft-check	0.001	NFT safety check

Example (Paid Request)

# Step 1: Get pricing + treasury address
curl https://sicarius-guard-640545264957.us-east4.run.app/v1/pricing

# Step 2: Send SOL to treasury address (returned in pricing response)
solana transfer <TREASURY_ADDRESS> 0.002

# Step 3: Use tx signature as payment proof
curl -X POST https://sicarius-guard-640545264957.us-east4.run.app/v1/scan \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <your_tx_signature>" \
  -d '{"mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}'

Security

• On-chain verification — Every payment is verified against Solana mainnet
• Replay protection — Each tx signature can only be used once
• Amount validation — Exact SOL amount must match endpoint pricing
• Freshness check — Transactions older than 10 minutes are rejected
• Verified live on mainnet — Tested with real SOL transfers

Access Tiers

Tier	Auth Method	Rate Limit
Free	None	100 calls/day per IP
x402 Pay-Per-Call	X-PAYMENT header (SOL tx sig)	Unlimited

🔧 Configuration

Variable	Description	Default
HELIUS_RPC_URL	Solana RPC endpoint (Helius recommended)	https://api.mainnet-beta.solana.com
PORT	API server port	3400
HOST	Bind address	0.0.0.0
BIRDEYE_API_KEY	Birdeye API key (optional, enriches scans)	—
TREASURY_WALLET	SOL payment recipient (x402)	—
CACHE_TTL_SECONDS	Cache duration	300
FREE_TIER_CALLS_PER_DAY	Free tier rate limit	100
UPSTASH_REDIS_REST_URL	Upstash Redis URL for persistent rate limiting	—
UPSTASH_REDIS_REST_TOKEN	Upstash Redis auth token	—

📊 Performance

Tested with 50-token bulk scan on Solana mainnet:

Metric	Value
Success rate	50/50 (100%)
Avg response time	5.4s
x402 payment verification	Verified live on mainnet

📦 Tech Stack

• Runtime: Node.js 22+ (ESM)
• Language: TypeScript 5.9
• Blockchain: @solana/web3.js (direct RPC, no wrapper SDKs)
• API: Express 5
• MCP: @modelcontextprotocol/sdk
• Market Data: Birdeye API v3
• NFT Data: Magic Eden v2 API (free tier)
• Wallet Intel: Helius DAS / Identity / Funded-By APIs
• Pool Data: GeckoTerminal API + Raydium V4 byte decode

🛡️ Why SicariusGuard?

Most token safety tools rely on third-party APIs that can be gamed. SicariusGuard reads raw mint account bytes directly from the blockchain — the same data the Solana runtime uses to execute transactions. No middleman, no stale data, no API that can be fooled.

Feature	SicariusGuard	RugCheck	GoPlus
Byte-level SPL analysis	✅	❌	❌
Token-2022 extension scanning	✅	❌	Partial
Jupiter honeypot simulation	✅	❌	❌
LP lock/burn detection	✅	✅	❌
Raydium V4 byte decode	✅	❌	❌
Token age analysis	✅	❌	❌
Deployer serial scammer detection	✅	❌	❌
NFT fraud detection	✅	❌	❌
Helius wallet reputation	✅	❌	❌
12-layer weighted scoring	✅	❌	❌
MCP server for AI agents	✅	❌	❌
x402 pay-per-call (SOL)	✅	❌	❌
Self-hosted (no vendor lock-in)	✅	❌	❌
Birdeye market enrichment	✅	❌	❌
Sub-6s full scan	✅	✅	✅

🔗 Related MCP Servers

Build powerful agentic workflows by combining SicariusGuard with these complementary MCP servers:

Server	Description	Use With SicariusGuard
Pentagonal	AI-powered smart contract auditing for Solidity & Anchor/Rust	Audit the contract → scan the token with SicariusGuard
Desk3	Real-time cryptocurrency market data	Get macro market context → validate token safety
AgentForge	DeFi safety layer — SPL approval scans & contract registry	Check approvals → scan token safety with SicariusGuard
Financial Datasets	Stock & market data for AI assistants	Cross-market correlation analysis

⭐ Star History

Star History Chart

---

📄 License

MIT — Built by Chronolapse411

🔗 Links

• npm: npmjs.com/package/sicarius-guard
• Live API: sicarius-guard-640545264957.us-east4.run.app
• GitHub: github.com/Chronolapse411/sicarius-guard
• Glama: glama.ai/mcp/servers/Chronolapse411/sicarius-guard
• Smithery: smithery.ai/server/chronolapse411/sicarius-guard
• Dev.to: How I Built a 12-Layer Token Safety Oracle
• Twitter/X: @chronolapse411
• Author: @Chronolapse411