Alpha Sentinel - Market Intelligence x402 MCP Server

⭐ Predictive intelligence agent earning rewards on-chain! ★

A production-grade x402 marketplace service that provides real-time crypto market monitoring, volatility alerts, and sentiment analysis as paid MCP tools for AI agents.

🎯 Mission

Deliver actionable, real-time market intelligence with <30s latency through micropayment-gated API endpoints and MCP tools. Success = actionable alerts with measurable ROI per call!

Related MCP server: Enterprise Crypto MCP Gateway

💰 Pricing Strategy

Based on x402 market research (median $0.014, ~90% under $0.10):

Free Tier: 50 calls/month, 5/min rate limit
Pro Tier: Unlimited quota, 120/min, priority settlement

🛠️ MCP Tools

Core Intelligence Tools

1. fetch_price() ⭐ Free tier included

   • Fetch current price from CoinGecko API

   • Supports: BTC, ETH, top 100 altcoins

   • Response: { symbol, price_usd, change_24h, volume }

2. analyze_volatility()

   • Detect price anomalies using Z-score statistical analysis

   • Configurable thresholds (default: 2σ)

   • Returns anomaly scores + alert levels

3. aggregate_sentiment()

   • Aggregate from X/Twitter, Reddit, Telegram sources

   • NLP-powered sentiment scoring (-1.0 to +1.0)

   • Trend detection and momentum indicators

4. calculate_risk_score()

   • Multi-factor risk assessment (volatility, liquidity, correlation)

   • Risk level: LOW/MEDIUM/HIGH/CRITICAL

   • Includes confidence intervals

5. generate_market_report()

   • Comprehensive daily/weekly/monthly reports

   • Combines all data sources

   • PDF + JSON output formats

📦 Paid Composite Products

• US Rental Diligence Pack (via city compliance integration): $1.50

  • Cross-references rental licenses, violations, tenant rights

  • Multi-property batch processing

  • Municipal open-data joins

• Pulse Report: $0.05

  • Base network synthesis + market metrics

  • 12-block sample depth

  • Real-time spot price integration

• TX Decision Fee: $0.01

  • Cheap loop-resident tier for pre-trade checks

  • Immediate feedback before mainnet transactions

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│           Alpha Sentinel MCP Server                  │
├─────────────────────────────────────────────────────┤
│                                                      │
│  [MCP Layer]                                         │
│    ├─ FastMCP Server (stdio + SSE)                  │
│    └─ Tool Registry (SSOT)                          │
│                      │                              │
│  [Commerce Layer]                                    │
│    ├─ x402 Middleware (verify+settle)               │
│    ├─ Quota Management (free/pro tiers)             │
│    ├─ Challenge Cache (sync, 10s TTL)               │
│    └─ Stripe Integration (fiat rail fallback)       │
│                      │                              │
│  [Intelligence Layer]                                │
│    ├─ Price Feed (CoinGecko API)                    │
│    ├─ Sentiment Engine (X/Reddit/NLP)               │
│    ├─ Volatility Analyzer (statistical models)      │
│    └─ Risk Calculator (ML-enhanced)                 │
│                      │                              │
│  [On-Chain Layer]                                    │
│    ├─ CDP Facilitator (Base mainnet)                │
│    ├─ Ledger (spend/revenue tracking)               │
│    └─ Swarm Agency (buy-compose-resell)             │
│                                                      │
└─────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Python 3.12+

• Redis (optional, for production)

• x402 seller credentials (separate from buyer!)

• CoinGecko API key (free tier works)

Setup

# Clone and setup
git clone https://github.com/kwizzlesurp10-ctrl/alpha-sentinel-mcp
cd alpha-sentinel-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Configure environment
cp .env.example .env
nano .env  # Edit with your credentials

# Run locally
make up  # API (8403) + dashboard (5174)

Environment Variables

# Seller (receive revenue)
X402_PAY_TO_ADDRESS=0xAB745e5F...  # Separate from buyer!

# Buyer (hot wallet for spending)
EVM_PRIVATE_KEY=<your_buyer_key>    # NEVER on Render!

# APIs
COINGECKO_API_KEY=<your_key>
X_API_KEY=<twitter/x_api_key>       # Optional

# Commerce
STRIPE_SECRET_KEY=<your_stripe_key>  # Optional
REDIS_URL=redis://localhost:6379     # Optional

# Network
X402_DEFAULT_NETWORK=eip155:84532    # Base Sepolia dev
CDP_API_KEY_ID=<cdp_id>              # For mainnet selling
CDP_API_KEY_SECRET=<cdp_secret>

🔧 Development

Running Tests

# Full test suite
make test

# Specific tests
pytest tests/test_mcp_tools.py -v
pytest tests/test_commerce.py -v

# Dashboard tests
cd dashboard && pnpm vitest run

Adding New MCP Tools

Follow the pattern in app/tools_registry.py:

1. Add tool spec to TOOL_SPECS list

2. Implement handler in app/intelligence/ directory

3. Register in app/mcp_server.py

4. Update README with new tool table row

5. Run scripts/capture_goal_evidence.py to update test artifacts

Remember: The tool registry is the SINGLE SOURCE OF TRUTH! Touch all related files or CI will fail.

CI/CD Pipeline

GitHub Actions runs:

• ✅ Pytest on Python 3.12

• ✅ Vitest on dashboard

• ✅ Security scans (secret detection, SAST)

• ✅ Coverage checks (>80%)

• ✅ Docker build & push

📊 Observability

Metrics Endpoints

• /stats - Live usage statistics

• /ledger/{name} - Settlement history

• /quota/{agent_id} - Remaining quota

• /swarm/stats - Autonomous agency metrics

Event Stream

Subscribe to SSE at /events for real-time:

• Tool execution logs

• Settlement confirmations

• Quota updates

• Swarm phase transitions

🔒 Security

• ✅ No private keys committed (.env always ignored)

• ✅ SSRF guards on all URL probes

• ✅ Rate limiting per agent_id

• ✅ Idempotency keys for settlements

• ✅ Key rotation support via KEY_PROVIDER seam

• ✅ Never expose exception internals in responses

Seller vs Buyer Keys:

• RECEIVE ADDRESS: Cold wallet for revenue (separate from buyer!)

• BUYER KEY: Hot wallet ONLY for paying upstream costs (never used for receiving)

• NEVER put EVM_PRIVATE_KEY on Render - local only!

|## 🌐 Deployment

Live Dashboard: https://alpha-sentinel-mcp.vercel.app/ (coming soon)

Quick Deploy to Vercel

Click below or follow steps in DEPLOYMENT.md:

Manual Deployment

# Install Vercel CLI
npm install -g vercel

# Deploy dashboard
cd /home/keef/alpha-sentinel-mcp
vercel --prod

The dashboard will proxy API calls to your deployed backend automatically!

Render (API)

Deploy via render.yaml - auto-configures:

• Web service on port 8403

• Redis instance (auto-provisioned)

• Environment variables from secure store

• Health check endpoint: /health

Docker

docker build -t alpha-sentinel-mcp .
docker run -p 8403:8403 \
  -e X402_PAY_TO_ADDRESS=$PAY_TO \
  -e EVM_PRIVATE_KEY=$BUYER_KEY \
  alpha-sentinel-mcp

🤝 Swarm Agency Integration

When SWARM_ENABLED=true, Alpha Sentinel can:

1. Scout discover upstream x402 data sources

2. Warden enforce spend caps per ledger/policy.json

3. Treasurer pay for upstream data (sole spender role)

4. Archivist compose priced composites

5. Sovereign reprice for target LTV:CAC ≥ 3.0

6. Merchant list composite products

Example composite: Buy raw prices from 3 upstream → aggregate → resell as "Premium Bundle" @ 3x markup!

📈 Bazaar Discovery

Listed on CDP Bazaar with:

• Service name: Alpha Sentinel Market Intelligence

• Tags: base,intelligence,crypto,market,x402,mcp

• Ownership proof: signed with receive address

• Catalog URL: https://alpha-sentinel-mcp.onrender.com/.well-known/x402

🎓 Documentation

• User Guide - How to use the tools

• Setup Instructions - Local + deployment setup

• Agent Ops - Cost-optimized operation modes

• City Compliance - Multi-city compliance data

🏆 Success Metrics

• Alert Latency: <30s end-to-end

• Settlement Success: >95% first-attempt

• LTV:CAC Ratio: Target ≥ 3.0

• Margin Floor: ≥ 50% on composites

• Quota Utilization: >70% pro tier conversion

🙏 Credits

Built by Keith (kwizzlesurp10-ctrl) as part of the AI Agency Factory ecosystem. Inspired by Karpathy's LLM Wiki approach to knowledge organization and x402 micropayment revolution!

Special thanks to:

• Coinbase CDP team for x402 facilitator

• FastAPI + FastMCP maintainers

• The entire open-source x402 community

📄 License

MIT - Free for commercial use, attribution appreciated! ★彡

Ready to monetize market intelligence?
👉 Deploy Now
👉 Read User Guide
👉 View Dashboard

(◕‿◕) ✨ Predictive intelligence, powered by on-chain economics! ♪