mcp server
sicarius-guard
Solana Token Safety Oracle for AI Agents & Trading Bots — byte-level SPL analysis, honeypot detection, Birdeye enrichment, MCP server
Set up
Runs on your computer. Pick your agent and operating system.
Before you start
- Node.js 20 or newer
{
"mcpServers": {
"sicarius-guard": {
"command": "npx",
"args": [
"-y",
"sicarius-guard"
]
}
}
}same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12
Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs
README
synced Oct 22, 2026🛡️ SicariusGuard
Solana Token & NFT Safety Oracle for AI Agents & Trading Bots
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
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
📄 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