Predict-Chain: Polymarket Odds + Probability Chain Reasoning for AI

⚠️ Pre-release / Beta software. API endpoints, tool signatures, and response shapes may change without major version bumps. All data is fetched live from Polymarket's public APIs — no guaranteed uptime or SLA.

A lightweight MCP server that gives AI models real-time Polymarket odds with dual-mode operation — single-event lookup (Mode A) and probability chain reasoning (Mode B) for "If X happens, what's next?" analysis. Uses Attena's semantic search as the primary discovery layer with Gamma API validation for live prices and liquidity.

Quick Start

npx @predict-mcp/predict-chain          # stdio mode (interactive)
PORT=3100 npx @predict-mcp/predict-chain  # HTTP mode

Requires Node.js >= 20.0.0. No API keys needed — read-only access to Polymarket's public APIs.

How to Search

Use single-topic queries. The tools cross-reference results across multiple searches — the AI model is the analyst, not a passive consumer of search output:

Bad:  search_markets("Iran Israel war oil price GDP impact")  → 0 results
Good:
  1. search_markets("Iran US military")   → find conflict proxy
  2. search_markets("oil price")          → find energy disruption markets
  3. search_markets("US recession")       → find economic downturn markets
  4. AI filters irrelevant results, builds chain manually

Compound queries often return zero Attena results. Break questions into single-topic searches and let the AI filter, cross-reference, and build the chain.

Dual Mode Architecture

Mode A — Event Lookup (1-2 tool calls)

For questions like "What are the odds on Bitcoin hitting $100K?"

search_markets → get_market_odds → optional analyze_market_context

Returns: yes/no prices as decimals and percentages, bid/ask spread, volume, liquidity rating, credibility score (0-1), and price change history.

Mode B — Chain Reasoning (4-7 tool calls)

For questions like "If the Fed cuts rates, what happens to USD and crypto?"

search_markets → propagate_chain(start_slug) or manual: find_related_events → get_conditional_odds

Returns: ranked probability chains with per-node analysis — P(node), volume, credibility, conditional transition probabilities, and joint path probabilities.

Tools

| Tool | Mode | Description | |------|------|-------------| | search_markets | Both | Dual-API semantic search — Attena discovery + Gamma validation. Returns active markets with live prices, volume, tags, and search source tracking (attena/gamma). Supports concise mode for token efficiency. | | get_market_odds | A | Single-market odds. Slug lookup via Gamma keyset API. Returns decimal prices, percentages, bid/ask, volume, liquidity, 1d/7d/30d price changes, category, and tags. | | analyze_market_context | A | Credibility assessment. Computes a 0-1 credibility score from log-linear liquidity model (45%), resolution source quality (30%), and price discovery age (25%). Generates a human-readable qualitative assessment. | | find_related_events | B | Downstream candidate discovery. Scores top 100 active markets on shared parent event (50%), keyword Jaccard overlap (30%), temporal proximity with 14-day half-life (18%), and volume quality (2%). Includes ranking reasons. | | get_event_timeline | B | Temporal ordering. Finds sibling markets under the same parent event, sorted by resolution date. Shows resolved and active sub-markets so the AI can determine chain directionality. | | get_conditional_odds | B | Transition probability. Computes P(B|A) between two markets using 4 derivation tiers: shared_parent_event → temporal<7d → temporal<30d → independent_estimation. Returns probability, confidence band, and confidence modifier. | | propagate_chain | B | End-to-end chain builder. Starting from one slug, recursively discovers downstream candidates, computes transition probabilities, and prunes low-probability paths (adaptive limits: 25/15/8/4 by depth). Returns ranked chains with per-node credibility and per-edge confidence. |

Dual-API Architecture

The server uses two APIs to maximize result quality:

1. Attena Search API (primary) — semantic search across Polymarket + Kalshi markets. Discovers markets by meaning, not just keywords. Results filtered to Polymarket-only server-side.
2. Polymarket Gamma API (validation + fallback) — validates Attena results against live keyset for current prices and active/closed status. Falls back to direct text search when Attena returns nothing.

All API calls cached in-memory (30s TTL). Rate limited at 1 req/sec with timestamp-based delay enforcement.

Configuration

MCP Client — stdio (recommended)

{
  "mcpServers": {
    "predict-chain": {
      "command": "npx",
      "args": ["-y", "@predict-mcp/predict-chain"]
    }
  }
}

MCP Client — HTTP

PORT=3100 npx @predict-mcp/predict-chain

{
  "mcpServers": {
    "predict-chain": {
      "url": "http://localhost:3100"
    }
  }
}

Other clients (Claude Desktop, Cursor, Warp, etc.)

Point at npx @predict-mcp/predict-chain for stdio, or http://localhost:3100 for HTTP.

Confidence & Credibility

Credibility score (0-1): computed from three factors using continuous formulas (no step-function cliffs):

| Factor | Weight | Method | |--------|--------|--------| | Liquidity | 45% | Log-linear interpolation from $5K (0.3) to $500K+ (1.0) | | Resolution source | 30% | Domain authority: .gov/IMF → 1.0, exchanges → 0.7, Reuters/Bloomberg → 0.6, HTTP → 0.3, empty → 0.1 | | Price discovery | 25% | Non-monotonic: >90 days → 0.8, <24 hours → 0.9 (near-resolution price IS the signal) |

Confidence bands: continuous SE-based formula with price-awareness and inflation factor (1.3 normal, 2.0 thin markets). Floor ±0.5%, cap ±15%. A 90% market has tighter bands than a 50/50 market.

Quick reference (± thresholds vary with price and volume):

| Volume | Typical Band | Trust | |--------|-------------|-------| | $500K+ | ±1-2% | Present directly | | $50K-$500K | ±3-5% | Include confidence warning | | <$50K | ±5-15% | Add "thin market — odds may be volatile" |

See math-formulas.md for the complete scoring formulas.

Development

npm install          # Install dependencies
npm run dev          # Start in dev mode with tsx (auto-reload)
npm run build        # Compile TypeScript
npm test             # Run unit tests (70 tests, ~120ms)
npm run test:integration  # Run integration tests against live APIs (95 total tests)
npm run lint         # ESLint

Integration tests hit the live Gamma and Attena APIs and auto-skip in CI (via process.env.CI).

License

MIT