HERMEX

01 Overview

Hermex turns every KOL tweet into a tradeable prediction market.

A Chrome Extension (Manifest V3) watches the X feed in real time. When an influential tweet is detected, the Hermes Agent backend generates a market proposal in under three seconds — with smart probabilities, resolution criteria and a simulated order book — then injects an inline prediction card directly below the tweet.

The dashboard at herm3x.com surfaces the same markets in a Polymarket-style live feed, with one-click betting routed through Binance Web3 Wallet.

02 How It Works

1. Browse X normally with the Hermex extension installed.
2. A MutationObserver detects KOL tweets in real time — zero polling.
3. The tweet payload is sent to POST /api/proposal on the Hermex backend.
4. Hermes Agent (LLM) analyzes the tweet and returns a structured market: question, YES/NO probabilities, resolution criteria, end date.
5. A prediction card renders below the tweet — showing odds, volume and liquidity.
6. One click opens the bet modal, signs via Binance Web3 Wallet, and routes the order.

03 Architecture

┌──────────────────────────────────────────────────────┐
│  Chrome Extension (Manifest V3)                      │
│  ├── Content Script  — DOM observer + card injection │
│  ├── Background SW   — API relay + config management │
│  └── Popup           — Settings, KOL list, stats     │
└───────────────┬──────────────────────────────────────┘
                │ REST / JSON
┌───────────────▼──────────────────────────────────────┐
│  Backend API  (Express + TypeScript + Bun)           │
│  ├── POST /api/proposal       — LLM market gen       │
│  ├── GET  /api/feed-markets   — Dashboard feed       │
│  ├── GET  /api/markets/search — Predict.fun lookup   │
│  ├── GET  /api/system         — Live system monitor  │
│  ├── GET  /api/logs           — Request log stream   │
│  └── GET  /api/health         — Health check         │
└───────┬──────────────────────┬───────────────────────┘
        │                      │
┌───────▼────────┐    ┌────────▼────────┐
│  Hermes Agent  │    │  Predict.fun    │
│  (LLM via      │    │  REST API       │
│   OpenRouter)  │    │  (Testnet/Main) │
└────────────────┘    └─────────────────┘

04 Features

05 Quickstart

Prerequisites

• Bun v1.0 or newer
• Chrome or any Chromium browser
• An LLM API key — OpenRouter, OpenAI or a compatible endpoint

1. Clone

# Clone the monorepo
git clone https://github.com/herm3x/hermes-agent.git
cd hermes-agent/hermex

2. Backend

cd backend
cp .env.example .env
# edit .env — add your OPENROUTER_API_KEY
bun install
bun run dev

The backend starts at http://localhost:6088. Open it in your browser to see the dashboard.

3. Chrome Extension

cd ../chrome-extension
bun install
bun run build

Open chrome://extensions, enable Developer mode, click Load unpacked and point to chrome-extension/dist. Or download the pre-built ZIP from the dashboard’s Install Extension panel.

06 Chrome Extension

The extension is a Manifest V3 package split into three surfaces. All three share a common TypeScript types package and a config store backed by chrome.storage.sync.

Content Script

Runs on *.x.com and *.twitter.com. A single MutationObserver watches for new tweet articles, extracts the author handle, text and permalink, then posts to the background service worker. Failed injections are retried on DOM churn & SPA navigation.

Background Service Worker

Handles network I/O (the content script cannot make cross-origin calls reliably), throttles requests against the dailyLimit counter, and caches proposals keyed by tweet ID to avoid duplicates.

Popup

Cobalt-glass settings panel. Fields: Backend API URL, Testnet toggle, Auto-propose, Min Followers, KOL Whitelist, and daily-usage stats. All changes persist instantly to chrome.storage.sync.

07 HTTP API

All routes are mounted under /api. JSON in, JSON out.

Example: generate a proposal

curl -X POST http://localhost:6088/api/proposal \
  -H "Content-Type: application/json" \
  -d '{
    "author": "CZ 🔶 BNB",
    "handle": "cz_binance",
    "text": "Guess who is licensed in Pakistan?",
    "tweetUrl": "https://x.com/cz_binance/status/2044759742531195257",
    "followers": 9100000
  }'

08 Configuration

Backend · .env

PORT=6088
LLM_PROVIDER=openrouter         # openrouter | openai | anthropic | custom
OPENROUTER_API_KEY=sk-or-v1-...
LLM_MODEL=nousresearch/hermes-3-llama-3.1-405b
PREDICT_FUN_BASE=https://api-testnet.predict.fun
ALLOWED_ORIGINS=chrome-extension://*,https://herm3x.com

Extension · popup settings

• Backend API URL — default http://localhost:6088
• Testnet Mode — route to Predict.fun testnet (default on)
• Auto-propose — auto-generate cards for KOL tweets (default on)
• Min Followers — ignore accounts below this threshold (default 50,000)
• KOL Whitelist — handles to always track regardless of follower count
• Daily Limit — max proposals per rolling 24h window (default 500)

09 Deploy

Production is a bare VPS: Bun + pm2 + nginx + certbot. No containers required.

# On the VPS
cd /opt/hermex/backend
git pull
bun install --production
NODE_ENV=production pm2 restart hermex --update-env

# nginx already proxies 443 → 6088 with a Let's Encrypt cert
sudo systemctl reload nginx

The dashboard is live at https://herm3x.com. Health check: GET /api/health.

10 Tech Stack

• Extension — TypeScript, Webpack, Manifest V3
• Backend — Bun, Express, TypeScript
• LLM — Hermes 3 (405B) via OpenRouter (swappable to OpenAI / Anthropic / custom)
• Markets — Predict.fun REST API
• Wallet — Binance Web3 Wallet (multi-chain: BSC, ETH, ARB, Polygon, Base)
• Deploy — Bun + pm2 + nginx + certbot on Ubuntu
• Frontend — vanilla JS + glassmorphism CSS, cobalt / royal-blue theme