Kelly

onboarding

# Kelly - AI-Powered Polymarket Intelligence

## Inspiration

Prediction markets like Polymarket contain valuable insights, but staying informed across hundreds of markets is overwhelming. We wanted to build an AI agent that acts like a personal research assistant - monitoring markets 24/7, connecting news events to trading opportunities, and surfacing only what matters to you. The goal: make prediction market intelligence as accessible as checking a news feed.

## What it does

Kelly is an intelligent agent system that helps users discover and track Polymarket prediction markets through natural language:

Core Features:

Interest-Based Discovery - Select topics (crypto, sports, politics, etc.) and Kelly finds relevant markets automatically
AI Chat Interface - Ask questions like "What are trending crypto markets?" and get instant, contextualized answers
Real-Time Market Data - Fetches live data from Polymarket's API including prices, volumes, and probabilities
Smart Filtering - Uses word-boundary matching to accurately filter markets by topic (e.g., "AI" won't match "Raiders")
News Integration - Web search tools (Tavily/Perplexity) connect market movements to real-world events
Streaming Responses - Server-sent events for real-time AI responses
Production Monitoring - Sentry integration for error tracking, performance monitoring, and user logs

Agent Architecture:

Orchestrator Agent - Routes requests and synthesizes multi-source information
Polymarket Agent - Searches markets, gets details, tracks trending opportunities
Research Agent - Web/news search to provide context for market analysis
Database Layer - SQLite stores user interests, watched markets, and notifications

## How we built it

Frontend (Next.js 16 + React 19)

Next.js with App Router and React Server Components
Tailwind CSS v4 for styling with custom design system
TypeScript for type safety
Sentry integration for error monitoring, performance tracking, and user session logs
Custom API client with streaming support

Backend (Node.js + Express)

Express API server with RESTful endpoints
TypeScript throughout the backend
Claude Sonnet 4.5 via Anthropic API for AI reasoning
Vercel AI SDK v4 for tool calling and streaming
Zod for schema validation
better-sqlite3 for local persistence

AI & APIs:

Anthropic Claude - Main reasoning engine with 11 tools available
Polymarket Gamma API - Free, unauthenticated market data (fetches 200+ events)
Tavily/Perplexity - Web search for news and context
Sentry - Real-time error tracking, logs, and performance monitoring
Streaming Architecture - SSE for real-time chat responses

Key Technical Decisions:

Used AI SDK v4 (not v6) - v6 had breaking changes we couldn't afford mid-hackathon
Client-side filtering for Polymarket search since title_contains param didn't work reliably
Word boundary regex for short topics (e.g., \bAI\b) to avoid false matches
Fallback to trending when no topic matches found
Both streaming and sync chat endpoints for flexibility
Sentry for production observability from day one

## Challenges we ran into

AI SDK Version Hell
- Started with v6, hit breaking changes with tool definitions
- Downgraded to v4 (stable) mid-development
- Had to manage zod compatibility (v3 vs v4)
Polymarket API Quirks
- Discovered outcomes/prices returned as JSON strings, not arrays ("[0.5, 0.5]" not [0.5, 0.5])
- title_contains query param didn't work - had to fetch 200 events and filter client-side
- No authentication required but rate limiting concerns
Short Keyword Matching
- "AI" was matching "Raiders", "Saints", "Raimondo"
- Solved with word-boundary regex: \bAI\b
Frontend Merge Conflicts
- Lost tsconfig.json and PostCSS config during branch merge
- CSS wasn't loading until we recreated PostCSS config for Tailwind v4
Hydration Errors
- Browser extension (JotForm) injecting attributes into SSR HTML
- Not actually our bug, but scary at first

## Accomplishments that we're proud of

Full-stack integration - Frontend, backend, AI, and real APIs all working together
13 comprehensive tests - 92% pass rate with real API calls (about $0.42 total cost)
Smart filtering - Word-boundary matching correctly filters niche topics
Streaming chat - Real-time AI responses with SSE
Production-ready error handling - Sentry logging, graceful fallbacks, connection status indicators
Clean architecture - Separation of concerns: API client, agents, tools, database
Real market data - Not mocks - actual Polymarket markets updating live
Observability from start - Sentry integrated for debugging and monitoring user behavior

Technical Wins:

Orchestrator agent successfully routes between 11 tools
Interest sync between frontend localStorage and backend database
Proper TypeScript throughout (no any abuse)
Responsive UI that works offline with clear status indicators
Sentry logs capture user actions, errors, and performance metrics

## What we learned

AI/LLM Development:

Tool calling works incredibly well for structured tasks like API queries
Streaming is essential for good UX - users see progress immediately
Version pinning is critical for AI SDKs (v6 broke us, v4 saved us)
Claude Sonnet 4.5 is excellent at synthesis and multi-step reasoning

Prediction Markets:

Polymarket's API is generous (no auth) but has quirks
Volume is a better sorting metric than recency for discovery
Users need filtering - 1000+ markets is overwhelming
Topic matching needs to be precise (word boundaries matter)

Full-Stack Integration:

Next.js 16 + React 19 is fast but docs are catching up
Tailwind v4 requires explicit PostCSS config (unlike v3)
Server/client separation is crucial for features like localStorage + DB sync
Error boundaries and fallbacks make or break UX
Sentry integration early saves hours of debugging later

Hackathon Strategy:

Start with stable versions, not bleeding edge
Test with real data early (we caught API bugs on day 1)
Have fallbacks for everything (trending when no matches, localStorage when backend down)
Document as you go (our TEST_REPORT.md was lifesaver for debugging)
Add monitoring tools like Sentry immediately for faster iteration

## What's next for Kelly

Short-term (MVP to Beta):

Background monitoring - Cron jobs to check markets every hour
Price alerts - Notify when probability crosses thresholds
WebSocket updates - Push notifications for real-time market changes
Market watchlist - Save specific markets to track closely
Historical data - Track price changes over time
Enhanced Sentry analytics - Custom dashboards for user behavior patterns

Medium-term (Beta to v1):

User accounts & auth - Multi-user support with NextAuth
Advanced filters - Date ranges, min volume, probability bands
Market analysis - AI-generated summaries of why probabilities changed
Portfolio tracking - Connect wallet to track actual positions
Mobile app - React Native for iOS/Android
Sentry performance optimization - Identify and fix slow queries

Long-term (v1+):

Custom agents per topic - Specialized agents for sports, politics, crypto
Social features - Share market insights, follow other users
AI trading suggestions - Not just discovery, but actual trade recommendations with reasoning
Integration with other markets - Kalshi, Manifold, etc.
News correlation engine - Automatically link news articles to market movements
Advanced Sentry alerting - Anomaly detection for unusual market activity

Technical Improvements: