Sicarius Guard README

🛡️ 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`

bash

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

Code

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

bash

# 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

bash

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

config.json

{
  "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)

bash

# Run directly — no cloning required
npx sicarius-guard

Install in Claude Code

Terminal

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

Install in Cursor

Or manually add to your Cursor MCP config:

config.json

{
  "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:

bash

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

Install from Source (Claude Desktop / Cursor)

config.json

{
  "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

Code

┌──────────────────────────────────────────────────────────────┐
│                       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

Code

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)

bash

# 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

🛡️ SicariusGuard

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

📑 Table of Contents

🔍 What It Does

On-Chain Safety (Layers 1-5)

LP & Token Maturity (Layers 6-8)

Intelligence & Reputation (Layers 9-12)

5-Axis Weighted Risk Scoring

🚀 Quick Start

📡 API Endpoints

REST API (Port 3400)

Example Request

Example Response (/v1/scan)

🤖 MCP Server (for AI Agents)

Available MCP Tools (11)

Install via npx (Recommended)

Install in Claude Code

Install in Cursor

Install in VS Code

Install from Source (Claude Desktop / Cursor)

🏗️ Architecture

💰 x402 Payment Protocol

How It Works

Pricing

Example (Paid Request)

Security

Access Tiers

🔧 Configuration

📊 Performance

📦 Tech Stack

🛡️ Why SicariusGuard?

🔗 Related MCP Servers

⭐ Star History

📄 License

🔗 Links

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

Example Response (`/v1/scan`)