
alpha-sentinel-mcp
io.github.kwizzlesurp10-ctrl/alpha-sentinel-mcp
Real-time crypto & tokenized equity intelligence MCP over x402 USDC on Base mainnet.
Documentation
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
-
fetch_price()ā Free tier included- Fetch current price from CoinGecko API
- Supports: BTC, ETH, top 100 altcoins
- Response:
{ symbol, price_usd, change_24h, volume }
-
analyze_volatility()- Detect price anomalies using Z-score statistical analysis
- Configurable thresholds (default: 2Ļ)
- Returns anomaly scores + alert levels
-
aggregate_sentiment()- Aggregate from X/Twitter, Reddit, Telegram sources
- NLP-powered sentiment scoring (-1.0 to +1.0)
- Trend detection and momentum indicators
-
calculate_risk_score()- Multi-factor risk assessment (volatility, liquidity, correlation)
- Risk level: LOW/MEDIUM/HIGH/CRITICAL
- Includes confidence intervals
-
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 (Vercel / production)
| Variable | Required | Purpose |
|---|---|---|
X402_PAY_TO_ADDRESS | yes | Seller USDC receive address (Base mainnet) |
CDP_API_KEY_ID | yes (mainnet) | Coinbase CDP x402 facilitator auth |
CDP_API_KEY_SECRET | yes (mainnet) | CDP Ed25519 secret for facilitator JWT |
X402_DEFAULT_NETWORK | yes | eip155:8453 (Base mainnet) |
REVENUE_NETWORK | recommended | Same as default; pins settlement rail |
PUBLIC_BASE_URL | yes | https://alpha-sentinel-mcp.vercel.app |
OPERATOR_TOKEN | recommended | Protects /ledger/*; cross-agent /quota |
COINGECKO_API_KEY | optional | Higher CoinGecko rate limits |
KV_REST_API_URL / KV_REST_API_TOKEN (or UPSTASH_REDIS_REST_*) | yes on mainnet/prod | Payment idempotency + settlement replay guard (SET NX, 24h TTL) |
X_API_KEY / REDDIT_* | optional | Reserved; sentiment uses Fear & Greed macro proxy today |
Never set EVM_PRIVATE_KEY on the server (buyer key stays local).
See .env.example for the full list (names only).
Vercel routing: Root vercel.json rewrites /health, /.well-known/*, /mcp, /tools/*, /llms.txt, and related API paths to api/index.py before the Mission Control SPA index.html fallback. All intelligence HTTP tools (including fetch_price) require x402 payment in production.
Live smoke (after deploy):
./scripts/smoke_live_deployment.sh https://alpha-sentinel-mcp.vercel.app
# or a preview URL from the PR
š§ 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:
- Add tool spec to
TOOL_SPECSlist - Implement handler in
app/intelligence/directory - Register in
app/mcp_server.py - Update README with new tool table row
- Run
scripts/capture_goal_evidence.pyto 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 (
.envalways ignored) - ā SSRF guards on all URL probes
- ā Rate limiting per agent_id
- ā Idempotency keys for settlements
- ā
Key rotation support via
KEY_PROVIDERseam - ā 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:
- Scout discover upstream x402 data sources
- Warden enforce spend caps per
ledger/policy.json - Treasurer pay for upstream data (sole spender role)
- Archivist compose priced composites
- Sovereign reprice for target LTV:CAC ā„ 3.0
- 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 Volatility(CDP Bazaar ā¤32 chars) - Tags:
volatility,crypto,intelligence,x402,mcp(max 5) - Ownership proof: signed with receive address
- Catalog URL:
https://alpha-sentinel-mcp.vercel.app/.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! āŖ
No installation packages available.
Remote
Related Servers
io.github.kwizzlesurp10-ctrl/apexseo-geo-mcp
Keyless Base USDC x402 MCP for live AI-crawler, GEO/AEO & JSON-LD citation audits.
io.github.kwizzlesurp10-ctrl/x402-mcp
Base mainnet x402 ($0.01 USDC) MCP gateway for 14+ US city housing & property compliance checks.
io.github.kwizzlesurp10-ctrl/x402orcle
Paid x402 Oracle MCP on Base USDC: demand counsel, Bazaar rewrites, and HTTP 402 diagnostics.