GitHub - Chronolapse411/sicarius-guard: Solana Token Safe...

🛡️ SicariusGuard

Solana Token Safety Oracle for AI Agents & Trading Bots

Real-time token safety analysis combining byte-level on-chain inspection, market intelligence, and wallet reputation scoring. 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

🔍 What It Does

SicariusGuard performs 7 layers of safety analysis on any Solana SPL token:

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?
📈 Market Intelligence	Birdeye API	Liquidity, volume, wash trading, manipulation
🔎 Wallet Reputation	Helius Identity + Funded-By	Is the deployer wallet a known scammer?

Weighted Risk Scoring (60/25/15 Model)

finalScore = (onChainRisk × 0.60) + (marketRisk × 0.25) + (reputationRisk × 0.15)

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

Weight	Source	What It Catches
60%	On-chain safety	Mint/freeze authority, honeypots, extensions
25%	Birdeye market data	Low liquidity, wash trading, price manipulation
15%	Helius wallet intel	Scammer wallets, suspicious funding chains

🚀 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 analysis + Birdeye + Helius wallet intel
`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/pricing`	x402 payment pricing table
`GET`	`/x402/stats`	Payment verification stats
`GET`	`/health`	Service health check

Example Request

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

# Full scan with Birdeye + Helius enrichment
curl https://sicarius-guard-640545264957.us-east4.run.app/v1/scan/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

Example Response (`/v1/scan`)

{
  "safety": {
    "safe": true,
    "riskScore": 0,
    "verdict": "SAFE",
    "reason": "SAFE — mint/freeze revoked, no dangerous extensions, supply OK",
    "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,
    "reason": "Sellable via Raydium → Quantum"
  },
  "holders": {
    "concentrated": false,
    "stats": { "top10Pct": 8.2 }
  },
  "birdeye": {
    "overview": {
      "price": 0.0000075,
      "liquidity": 3511099,
      "marketCap": 631226030,
      "holder": 999749
    },
    "marketRisk": { "verdict": "MARKET_SAFE", "flags": [] }
  },
  "walletIntel": {
    "creatorAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "reputation": {
      "verdict": "TRUSTED",
      "riskScore": 0,
      "flags": []
    }
  },
  "combined": {
    "safe": true,
    "riskScore": 0,
    "marketRiskScore": 0,
    "reputationScore": 0,
    "finalScore": 0,
    "verdict": "SAFE",
    "summary": "All checks passed — token appears safe"
  }
}

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

Available MCP Tools (7)

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	✅
`full_token_scan`	7-layer scan: on-chain + Birdeye market + Helius wallet reputation	✅
`get_wallet_reputation`	Helius DAS identity, funding chain, deployer age analysis	✅
`get_market_intel`	Birdeye market data: price, volume, liquidity, risk flags	✅
`batch_scan`	Parallel 7-layer scan of up to 10 tokens per call	✅

Usage with 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"
      }
    }
  }
}

Usage via npx

# Run directly without cloning
npx sicarius-guard

🏗️ Architecture

┌──────────────────────────────────────────────────────────────┐
│                       SicariusGuard                           │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────────┐ │
│  │ REST API    │  │ MCP Server  │  │ x402 Payment Gate    │ │
│  │ Express 5   │  │ stdio       │  │ SOL Micropayments    │ │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬───────────┘ │
│         │                │                     │             │
│  ┌──────▼────────────────▼─────────────────────▼───────────┐ │
│  │                  Core Safety Engine                      │ │
│  │                                                          │ │
│  │  ┌────────────┐ ┌──────────┐ ┌───────────────────────┐  │ │
│  │  │ token_     │ │honeypot_ │ │ holder_               │  │ │
│  │  │ safety.ts  │ │sim.ts    │ │ analysis.ts           │  │ │
│  │  └────────────┘ └──────────┘ └───────────────────────┘  │ │
│  │                                                          │ │
│  │  ┌────────────────────┐  ┌────────────────────────────┐ │ │
│  │  │ birdeye.ts         │  │ helius_wallet.ts           │ │ │
│  │  │ Market Intelligence│  │ Wallet Reputation (15%)    │ │ │
│  │  │ • Price/Volume     │  │ • Identity API             │ │ │
│  │  │ • Liquidity        │  │ • Funded-By chain          │ │ │
│  │  │ • Wash trading     │  │ • Scammer detection        │ │ │
│  │  └────────────────────┘  └────────────────────────────┘ │ │
│  └──────────────────────────────────────────────────────────┘ │
│                         │                                     │
│         ┌───────────────┼───────────────┐                    │
│         ▼               ▼               ▼                    │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │ Solana RPC  │ │ Birdeye API │ │ Helius DAS  │           │
│  │ (Helius)    │ │ (Market)    │ │ (Wallet)    │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
└──────────────────────────────────────────────────────────────┘

💰 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)
`/v1/check`	0.001
`/v1/scan`	0.002
`/v1/honeypot`	0.0005
`/v1/holders`	0.0005

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
Wallet Intel: Helius DAS / Identity / Funded-By APIs

🛡️ 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	✅	❌	❌
Helius wallet reputation	✅	❌	❌
Weighted multi-source 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

📄 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
Dev.to: How I Built a 7-Layer Token Safety Oracle
Twitter/X: @chronolapse411
Author: @Chronolapse411

推荐订阅源

Hacker News - Newest: "AI"

🛡️ SicariusGuard

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

🔍 What It Does

Weighted Risk Scoring (60/25/15 Model)

🚀 Quick Start

📡 API Endpoints

REST API (Port 3400)

Example Request

Example Response (`/v1/scan`)

Available MCP Tools (7)

Usage with Claude Desktop / Cursor

Usage via npx

🏗️ Architecture

💰 x402 Payment Protocol

How It Works

Pricing

Example (Paid Request)

Security

Access Tiers

🔧 Configuration

📊 Performance

📦 Tech Stack

🛡️ Why SicariusGuard?

🔗 Related MCP Servers

📄 License

🔗 Links

推荐订阅源

Hacker News - Newest: "AI"

🛡️ SicariusGuard

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

🔍 What It Does

Weighted Risk Scoring (60/25/15 Model)

🚀 Quick Start

📡 API Endpoints

REST API (Port 3400)

Example Request

Example Response (/v1/scan)

Available MCP Tools (7)

Usage with Claude Desktop / Cursor

Usage via npx

🏗️ Architecture

💰 x402 Payment Protocol

How It Works

Pricing

Example (Paid Request)

Security

Access Tiers

🔧 Configuration

📊 Performance

📦 Tech Stack

🛡️ Why SicariusGuard?

🔗 Related MCP Servers

📄 License

🔗 Links

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

Example Response (`/v1/scan`)