Polymarket Insight Extractor

Polymarket Insight Extractor is a research-only web app that helps you discover and analyze Polymarket prediction markets.

It fetches public market data, lets you search by interests (keywords/phrases/sentences), filters markets by time/probability/status, ranks results with a balanced scoring system, and (optionally) shows related news.

Safety / what this app does NOT do

This project is strictly for data extraction and research.

It will never:

• place trades
• connect wallets
• sign transactions
• call buy/sell endpoints
• automate betting

Disclaimer shown in the UI:

For research purposes only. This tool does not execute trades and does not provide financial advice.

Quick start (run locally)

Prereqs:

• Node.js 20+ (works with Node 24)
• npm 9+

Install dependencies:

npm install

Create backend config:

cp backend/.env.example backend/.env

Run frontend + backend together:

npm run dev

Open:

• Frontend: http://localhost:5173
• Backend: http://localhost:8787 (health: /api/health)

How to use (in the UI)

1. In Interests / categories, type one or more interests (comma-separated) and click Add.
   • Examples: AI companies, US politics, crypto regulation next week, sports finals this month
2. Open the Filters panel and optionally choose:
   • Close window (tomorrow / 3 days / 1 week / 1 month / custom)
   • Probability range (YES-only / NO-only / either)
   • Market status (open / resolving soon / closed)
3. Choose Sort and Ranking mode:
   • Ranking mode defaults to Balanced (uses both probability + time scores)
4. Click Search markets.
5. Review each market card:
   • Title + description + close time
   • YES/NO probabilities (or an outcomes list for multi-outcome markets)
   • Variant indicator if Polymarket offers multiple time-based versions
   • “Why this ranked here” explanation (keyword/probability/time scores)
   • Related news (if configured)

Optional: "My data" (wallet positions & trades)

The UI includes an optional My data panel where you can enter an EVM wallet address (e.g. 0x…) to fetch read-only:

• positions (with PnL fields when available)
• recent trades (sample)

This uses the Polymarket Data API via the backend (so no credentials are stored in the browser).

Backend endpoints:

• GET /api/my-data/summary?user=0x...
• GET /api/my-data/positions?user=0x...
• GET /api/my-data/trades?user=0x...

Config (optional) in backend/.env:

• DATA_API_BASE_URL=https://data-api.polymarket.com
• DATA_API_TOKEN=... (only if required by future/protected routes)

Optional: enable news enrichment

News is provided via a swappable backend provider. By default it’s disabled (mock provider returns no news).

To enable, set in backend/.env:

• NEWS_PROVIDER=serpapi and set SERPAPI_KEY=... (Google News via SerpAPI)
  • or
• NEWS_PROVIDER=newsapi and set NEWSAPI_KEY=... (NewsAPI)

Then restart npm run dev.

Build

npm run build

Troubleshooting

• If the UI can’t reach the backend in dev, ensure the backend is running on http://localhost:8787.
• If you change ports, update backend/.env and/or the Vite proxy in frontend/vite.config.ts.

Developer documentation

If you want to understand the internal architecture, Polymarket endpoint usage, scoring logic, and extension points (news + future AI), see:

• DEVELOPER_GUIDE.md