DeFi Research Agent

An AI-powered DeFi research and trading intelligence agent built with the NullShot Framework for real-time market analysis and portfolio management.

Overview

This project consists of two main components that work together to provide intelligent DeFi research capabilities:

1. DeFi Agent - A conversational AI agent powered by Google's Gemini API
2. DeFi MCP Server - A Model Context Protocol server providing real-time blockchain data and trading tools

Architecture

┌─────────────────────────────────────────────────┐
│                  Frontend                       │
│         (Next.js Web Interface)                 │
└─────────────────┬───────────────────────────────┘
                  │
                  │ HTTP/WebSocket
                  │
┌─────────────────▼───────────────────────────────┐
│              DeFi Agent                         │
│      (Cloudflare Durable Object)                │
│                                                  │
│  • Gemini 2.0 Flash Integration                 │
│  • Conversational AI Interface                  │
│  • Session Management                           │
│  • NullShot Agent Framework                     │
└─────────────────┬───────────────────────────────┘
                  │
                  │ MCP Protocol
                  │
┌─────────────────▼───────────────────────────────┐
│            DeFi MCP Server                      │
│      (Cloudflare Durable Object)                │
│                                                  │
│  Tools:                                         │
│  • getTrendingPools - Discover hot pools       │
│  • getTokenData - Price & market data          │
│  • getPoolChart - OHLCV charts                 │
│  • getPortfolio - Track holdings               │
│  • getSwapQuote - Price comparisons            │
│  • executeSwap - Gasless transactions          │
│  • webSearch - Research capabilities           │
│                                                  │
│  Data Sources:                                  │
│  • GeckoTerminal API (17+ chains)              │
│  • Jupiter Aggregator (Solana DEX)             │
│  • CoinGecko API (Token data)                  │
│  • Tavily API (Web research)                   │
└─────────────────────────────────────────────────┘

Features

DeFi Agent

• Real-time conversational interface for DeFi research
• Powered by Google Gemini 2.0 Flash Experimental
• Session-based conversation management via Durable Objects
• Automatic tool invocation for market analysis
• WebSocket and SSE support for streaming responses

DeFi MCP Server

• Market Intelligence: Discover trending pools across 17+ blockchain networks
• Token Analysis: Real-time price data, market cap, volume, and liquidity metrics
• Portfolio Tracking: Monitor token holdings and calculate portfolio values
• Swap Quotes: Get best prices across multiple DEX aggregators
• Gasless Swaps: Execute trades without holding native tokens for gas
• Web Research: Integrated search for DeFi news and analysis
• Multi-chain Support: Ethereum, BSC, Polygon, Arbitrum, Optimism, Base, Solana, and more

Technology Stack

DeFi Agent

• Runtime: Cloudflare Workers with Durable Objects
• Framework: NullShot Agent Framework
• LLM: Google Gemini 2.0 Flash Experimental
• HTTP Server: Hono
• Language: TypeScript

DeFi MCP Server

• Runtime: Cloudflare Workers with Durable Objects
• Protocol: Model Context Protocol (MCP)
• Framework: NullShot MCP SDK
• APIs: GeckoTerminal, Jupiter, CoinGecko, Tavily
• Language: TypeScript

Project Structure

defi-agent-repo/
├── defi-agent/              # AI Agent Worker
│   ├── src/
│   │   ├── agent.ts         # Agent implementation
│   │   └── index.ts         # Worker entry point
│   ├── wrangler.toml        # Cloudflare config
│   └── package.json
│
├── defi-mcp/                # MCP Server Worker
│   ├── src/
│   │   ├── server.ts        # MCP server implementation
│   │   ├── services/        # External API integrations
│   │   │   ├── coingecko.ts
│   │   │   ├── jupiter.ts
│   │   │   ├── aggregator.ts
│   │   │   └── tavily.ts
│   │   ├── tools/           # MCP tool definitions
│   │   │   ├── market-data.ts
│   │   │   ├── portfolio.ts
│   │   │   ├── swap.ts
│   │   │   └── research.ts
│   │   └── index.ts         # Worker entry point
│   ├── wrangler.toml        # Cloudflare config
│   └── package.json
│
└── _archive/                # Historical development files

Getting Started

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• Cloudflare account (for deployment)
• API Keys:
  • Google Generative AI API Key (Gemini)
  • CoinGecko Pro API Key
  • Tavily API Key

Installation

1. Clone the repository:

git clone <repository-url>
cd defi-agent-repo

2. Install dependencies for both components:

cd defi-mcp && pnpm install
cd ../defi-agent && pnpm install

3. Configure environment variables:

For DeFi MCP Server, create .dev.vars:

COINGECKO_API_KEY=your_coingecko_pro_key
TAVILY_API_KEY=your_tavily_key

For DeFi Agent, add secrets via Wrangler:

wrangler secret put GOOGLE_GENERATIVE_AI_API_KEY

Development

Run the MCP server locally:

cd defi-mcp
pnpm dev

Run the agent locally:

cd defi-agent
pnpm dev

Deployment

Deploy the MCP server first:

cd defi-mcp
pnpm deploy

Then deploy the agent:

cd defi-agent
pnpm deploy

Update the DEFI_MCP_URL in defi-agent/wrangler.toml with your deployed MCP server URL.

API Endpoints

DeFi Agent

• GET / - Agent information
• GET /health - Health check with capabilities
• POST /sessions - Create new session
• GET /sessions/:id/stream - SSE stream endpoint
• WebSocket /sessions/:id - WebSocket connection

DeFi MCP Server

• GET / - Server information
• GET /health - Health check
• GET /sse - MCP SSE transport
• GET /ws - MCP WebSocket transport (upgrade)
• GET /api/trending - Public trending pools endpoint

Available Tools

Market Data Tools

• getTrendingPools - Get trending pools by network, sorted by volume
• getTokenData - Get comprehensive token information and price data
• getPoolChart - Get OHLCV chart data for pools

Portfolio Tools

• getPortfolio - Track and value token holdings across networks

Trading Tools

• getSwapQuote - Get swap quotes from aggregators
• executeSwap - Execute gasless swaps via Jupiter

Research Tools

• webSearch - Search the web for DeFi-related information

Supported Networks

Ethereum, BSC, Polygon, Avalanche, Fantom, Arbitrum, Optimism, Cronos, Celo, Base, Solana, zkSync, Linea, Mantle, Scroll, PulseChain, Mode

Development Notes

NullShot Framework

This project is built on the NullShot Framework, which provides:

• Agent orchestration and session management
• MCP protocol implementation
• Cloudflare Workers integration
• Type-safe tool definitions

Durable Objects

Both components use Cloudflare Durable Objects for:

• Stateful session management
• Persistent conversation history
• Real-time WebSocket connections
• Edge computing scalability

Known Limitations

• Swap execution currently supports Solana only (via Jupiter)
• Some networks may have limited pool data availability
• API rate limits apply based on your CoinGecko tier
• Gemini API token limits may affect long conversations

Future Enhancements

• Multi-chain swap support beyond Solana
• Advanced charting and technical indicators
• Portfolio rebalancing recommendations
• Price alerts and notifications
• Historical portfolio performance tracking
• Integration with more DEX aggregators

License

MIT

Built With

• NullShot Framework - AI Agent & MCP infrastructure
• Cloudflare Workers - Edge computing platform
• Google Gemini - Large language model
• GeckoTerminal - DeFi market data
• Jupiter - Solana swap aggregator
• CoinGecko - Cryptocurrency data
• Tavily - AI search API

Support

For issues, questions, or contributions, please open an issue in the repository.