Polymaxx Simulator

An AI agent that watches Polymarket for whale trades, decides with AI whether to copy them, and executes real transactions onchain through KeeperHub.

Live dashboard: polymaxx-simulator.vercel.app Demo video: [https://youtu.be/BWd5fZ8_Z90] Example transaction: [https://sepolia.basescan.org/tx/0xe605fd3982f6ae989c18718bd48439b5ebed7d2c12126cd146db29deb2f7155d] on Base Sepolia via KeeperHub

What It Does

1. Every 30 minutes, the agent scans active Polymarket markets
2. For each market, it independently checks both outcome sides (e.g. Yes and No, or Team A and Team B) for large buy trades - sells are ignored entirely
3. If a whale buy of $1,000+ is detected on either side, Groq AI (Llama 3.3 70B) analyzes the signal and decides: COPY, REVERSE, or SKIP
4. If the AI decides to act, the agent simulates the transaction first (no gas spent if it would fail), then executes for real through KeeperHub's Direct Execution API on Base Sepolia
5. Every action - detected, decided, executed is logged with a full audit trail, visible on the public dashboard

Tech Stack

• Node.js backend
• Groq AI for decision making
• KeeperHub Direct Execution API for onchain execution (simulate-first, idempotent retries)
• Base Sepolia testnet
• Static HTML dashboard (Vercel) for public visibility into agent activity

Quick Start

# Install dependencies
cd backend && npm install

# Start the server (auto-restart on file changes)
npm run dev

Environment Variables

Create a backend/.env file:

GROQ_API_KEY=your_groq_key
KEEPERHUB_API_KEY=your_keeperhub_org_api_key
KEEPERHUB_API_BASE_URL=https://app.keeperhub.com
WHALE_MIN_TRADE_USD=1000
WHALE_WATCH_INTERVAL_MS=1800000

Note: KEEPERHUB_API_KEY must be an organization API key (Direct Execution enabled), not a webhook-specific key.

How It Works

Scan active markets (every 30 min)
        |
        v
Check BOTH outcome sides independently for whale BUY activity
        |
        v
Groq AI decides: COPY / REVERSE / SKIP
        |
        v
Simulate the trade (catch failures before spending gas)
        |
        v
Execute for real via KeeperHub Direct Execution API
        |
        v
Transaction hash returned, logged, and shown on the dashboard

Project Structure

backend/
  dashboard/
    index.html              # Public read-only dashboard (Vercel)
  src/
    scripts/
      testKeeperHubTrade.js # Manually trigger a real trade for testing
    services/
      aiDecisionService.js   # Groq AI reasoning layer
      executionEngine.js     # Scans markets, dispatches decisions
      auditService.js        # KeeperHub Direct Execution + audit trail
      polymarketService.js   # Polymarket market/orderbook interface
    config/                  # App configuration
    routes/                  # API routes
    server.js                # Entry point

API Endpoints

Route	Description
GET /health	Health check
GET /api/v1/simulator/status	Engine config and stats
GET /api/v1/simulator/markets	Currently active Polymarket markets
GET /api/v1/simulator/live-preview	Live whale activity per market (no AI/execution triggered)
GET /api/v1/simulator/audit-trail	Log of all trades the agent has executed
POST /api/v1/simulator/copy-trade	Manually trigger analysis + execution for a specific market

Reliability

• Simulate-before-execute — every trade is dry-run tested before any gas is spent
• Idempotency keys — retried requests can never accidentally execute the same trade twice
• Exponential backoff retries — transient network/server errors are retried automatically; non-retryable errors fail fast
• Buy-only whale detection — sells are filtered out at the source, so the agent only reacts to genuine directional conviction

Demo

Watch the agent execute a real transaction on Base Sepolia via KeeperHub:

[https://youtu.be/BWd5fZ8_Z90]

License

MIT