SicariusGuard – Solana token safety oracle for AI agents (MCP server)

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

20 Commits

20 Commits

.github/workflows

.github/workflows

scripts

scripts

src

src

.dockerignore

.dockerignore

.env.example

.env.example

.gitignore

.gitignore

CHANGELOG.md

CHANGELOG.md

CONTRIBUTING.md

CONTRIBUTING.md

Dockerfile

Dockerfile

LICENSE

LICENSE

README.md

README.md

glama.json

glama.json

package-lock.json

package-lock.json

package.json

package.json

tsconfig.json

tsconfig.json

Repository files navigation

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

🤖 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 (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:
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 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: " \ -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

About

Solana Token Safety Oracle for AI Agents & Trading Bots — byte-level SPL analysis, honeypot detection, Birdeye enrichment, MCP server

Topics

security

blockchain

cryptocurrency

ai-agents

solana

defi

birdeye

honeypot-detection

helius

mcp-server

x402

rug-pull-detection

token-safety

Resources

Readme

License

MIT license

Contributing

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases 1

v1.0.0 — Production Launch

Latest

May 12, 2026

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

TypeScript 99.5%

Other 0.5%