An AI-powered Web3 blockchain intelligence agent built with Vercel AI SDK, Next.js, Blockscout MCP, and Redis caching.

Ask natural language questions about blockchain data and get AI-reasoned insights powered by real-time on-chain data.

• AI-Powered Blockchain Analysis: Ask natural language questions about on-chain activity
• Persistent Chat History: Cloud-based chat storage with Supabase, syncs across devices
• Advanced Analysis Modes: Full account analysis, DeFi positions, NFT portfolios, transaction tracing
• Multi-Layer Caching: Redis caching for faster responses and reduced API calls
• Blockscout MCP Integration: Real-time blockchain data from multiple chains
• Conversational Context: Maintains conversation history across requests
• Rate Limiting: Built-in protection against API abuse
• Multi-Chain Support: Ethereum, Base, Optimism, Polygon, Arbitrum
• Smart Query Parsing: Natural language understanding with ENS support
• Docker Ready: Easy deployment with Docker and NodeOps

• Node.js 18+
• OpenAI API Key
• Supabase for chat persistence
• (Optional) Upstash Redis for production caching

1. Clone and install dependencies:

git clone <repository-url>
cd nodeops-web3-agent-node
pnpm install

2. Set up environment variables:

# Create .env.local file
cp .env.local.example .env.local

Edit .env.local and add your credentials:

OPENAI_API_KEY=sk-proj-your-key-here

# Supabase for chat persistence
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Optional: Upstash Redis for production caching
UPSTASH_REDIS_REST_URL=https://...
UPSTASH_REDIS_REST_TOKEN=...

3. Run the development server:

pnpm dev

4. Open http://localhost:3000/web3-agent

Try asking these questions:

• "What's the latest block on Ethereum?"
• "Show me the top 10 holders of USDC"
• "Analyze wallet: 0x..."
• "Show me recent events for contract 0x..."
• "What's the current health status of Base?"

[User Chat UI] → [Backend API] → [Redis Cache Check]
                                       ↓
                    [Cache Hit] ←→ [Cache Miss]
                         ↓                  ↓
                   [AI Response]    [Blockscout MCP] → [Blockchain Data]
                         ↓                              ↓
                   [Cache & Return]              [Process & Cache]

1. MCP Response Cache: Blockchain data cached for 30s-5min based on type
2. AI Output Cache: AI responses cached for 1 hour for identical queries
3. Conversation Context: Multi-turn context stored for 24 hours
4. Rate Limiting: Sliding window (10 req/sec) per IP/user

pnpm dev              # Start development server
pnpm build            # Build for production
pnpm start            # Start production server
pnpm lint             # Run linter

pnpm docker:dev       # Start with docker-compose
pnpm docker:build     # Build Docker image
pnpm docker:down      # Stop containers

1. Build the Docker image:

pnpm docker:build

2. Deploy using the NodeOps template:

pnpm deploy

Or use the NodeOps dashboard to deploy from nodeops/template.yaml

Set these in NodeOps environment configuration:

• OPENAI_API_KEY (required)
• UPSTASH_REDIS_REST_URL (required for production)
• UPSTASH_REDIS_REST_TOKEN (required for production)
• BLOCKSCOUT_MCP_URL (optional, defaults to production)
• DEFAULT_CHAIN (optional, defaults to ethereum)

The agent uses a multi-layer caching strategy:

• Latest Block: 30 seconds
• Token Holders: 5 minutes
• Account Summary: 1 minute
• Contract Events: 5 minutes
• AI Output: 1 hour
• Conversation: 24 hours

See Cache Configuration for details.

• PRD - Product requirements
• Project Plan - Revised plan with caching
• References - External resources
• Environment Setup - Setup guide
• API Reference - API documentation

• Ethereum (Chain ID: 1)
• Base (Chain ID: 8453)
• Optimism (Chain ID: 10)
• Polygon (Chain ID: 137)
• Arbitrum (Chain ID: 42161)

• 10 requests per second per IP/user
• Cached responses don't count toward rate limit
• AI output caching reduces token usage

Run test queries:

npm run test-demo-queries

Or manually test the chat interface at /web3-agent

The agent includes built-in monitoring:

• Cache hit/miss rates
• Response latency tracking
• Rate limiting metrics
• Error logging

Contributions welcome! Please read the Project Plan for architecture details.

MIT License - see LICENSE file for details.

• Vercel AI SDK
• Blockscout MCP
• NodeOps
• Upstash Redis

For issues or questions:

• Check docs directory
• Review Project Plan
• Open an issue on GitHub