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!

💰 Pricing Strategy

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

Resource	Price	Quota (Pro)	Description
price_feed()	$0.005	5000/mo	Real-time price lookup
volatility_alerts()	$0.02	500/mo	Anomaly detection + thresholds
sentiment_analysis()	$0.01	1000/mo	Social sentiment aggregation
risk_assessment()	$0.03	300/mo	Multi-factor risk scoring
market_report()	$0.15	50/mo	Comprehensive daily report
Tool Credit Pack	$1.00	100 calls	Flexible credits bundle

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! ♪