orcatrace-mcp

MCP server for OrcaTrace — pay-per-call Polymarket intelligence for AI agents. Track smart money and see what others miss across 42K prediction markets: quality-gated repricings with order-book microstructure, tracked-whale entries annotated with each wallet's hold-to-resolution calibration (follow or fade), AI-detected predetermined-outcome markets, on-demand single-market research, and 4-hourly synthesized digests — one unified, index-polled feed.

Pay per call with USDC on Base via x402 — no account, no API key.

• 5 free tools — no wallet, no API key.
• 8 paid tools — flat per-call USD prices ($0.01–$1.00), settled in USDC on Base Mainnet via x402.

The whale track record is free and verifiable. get_track_record publishes the aggregate hold-to-resolution win rate, follow/fade ROI, per-odds-band breakdown, and top wallets with full public addresses — so you can cross-check every claim on Polymarket before you pay. Preview every paid response shape free with get_sample.

---

Quick start

Free tier (no wallet)

{
  "mcpServers": {
    "orcatrace": {
      "command": "npx",
      "args": ["-y", "orcatrace-mcp"]
    }
  }
}

You get get_index, get_pulse, get_digest_brief, get_sample, get_track_record.

Paid tier (with wallet)

Add an EVM wallet private key (0x-prefixed) that holds USDC on Base Mainnet:

{
  "mcpServers": {
    "orcatrace": {
      "command": "npx",
      "args": ["-y", "orcatrace-mcp"],
      "env": { "PRIVATE_KEY": "0x..." }
    }
  }
}

The paid tools then settle each call automatically.

Install snippets

Claude Code:

claude mcp add orcatrace -- npx -y orcatrace-mcp
# with a wallet:
claude mcp add orcatrace --env PRIVATE_KEY=0x... -- npx -y orcatrace-mcp

Claude Desktop / Cursor: add the JSON block above to your MCP config (claude_desktop_config.json or .cursor/mcp.json).

---

Tools

Free tools

Tool	Endpoint	Description
get_index	GET /v1/index	Current feed index — poll target to detect new items (~10min cadence).
get_pulse	GET /v1/pulse	Top-3 24h repricings (noise-filtered) + a digest teaser — the free hook.
get_digest_brief	GET /v1/digest/brief	Digest teaser: title + summary, no analysis (full digest is get_digest).
get_sample	GET /v1/sample	Static samples of every paid response shape (signal, whales, digest).
get_track_record	GET /v1/track-record	Verifiable whale-calibration scorecard: win rate, follow/fade ROI, per-odds-band breakdown, top-10 wallets with full public addresses.

Paid tools

Tool	Endpoint	Price (USD)	Description
get_latest	GET /v1/latest	$0.01	Most recent feed item — mover, whale entry (with calibration), or predetermined signal.
get_signal	GET /v1/signal	$0.01	One feed item: quality-gated mover (+microstructure), named whale entry, or predetermined signal. Optional index.
get_signals	GET /v1/signals	$0.03	Batch of up to 20 feed items. Optional since, count, type (mover | whale_entry | predetermined).
get_resolving	GET /v1/resolving	$0.02	Markets resolving within withinHours (1–72): odds, contested/converged, liquidity, microstructure. Optional minLiquidity, includeNoise.
get_digest_history	GET /v1/digest/history	$0.05	Historical digests (up to 7 days, 4h cadence). Optional hours, limit.
get_whales	GET /v1/whales	$0.05	Whale calibration table: per-wallet win rates by odds band, mirror/fade ROI, follow/fade labels (min 30 resolved entries).
get_digest	GET /v1/digest	$0.10	Full Polymarket Intelligence Digest (every 4h): what repriced and why across 42K markets — synthesized analysis.
get_research	GET /v1/research	$1.00	Single-market deep-dive: 7-day price action + order book + whale positioning + news, synthesized into a thesis. Requires market slug.

Prices are flat per call — no bundles, no entitlements. Confirm live prices any time via the free get_sample / the site.

---

How payments work (x402)

OrcaTrace speaks the x402 exact scheme. The API's 402 advertises a Base (USDC, EIP-3009) rail; this MCP settles on Base:

1. The MCP requests a paid endpoint. With no payment, the API replies HTTP 402 with the accepted terms.
2. If PRIVATE_KEY is set, the MCP settles the call via the standard @x402/fetch V2 client and retries. If no key is set, the MCP returns the 402 price terms so you can see the cost without paying.
3. The API returns the data plus a payment block.

You are never charged for an error. The feed and digest routes are compute-first / settle-after — the full answer is computed before you are charged, and the digest returns 503 (no charge) rather than serving stale. The proxied-compute routes (get_resolving, get_whales, get_research) settle-early with a guaranteed refund — if the API charges but cannot deliver, the payment is refunded.

No accounts, no API keys — just a wallet with USDC on Base Mainnet.

---

Environment variables

Variable	Required	Description
PRIVATE_KEY	No	0x-prefixed wallet key with USDC on Base Mainnet. Required to pay the 8 paid tools on a live API. Free tools work without it; without a key the paid tools surface the 402 price terms.
ORCATRACE_API_URL	No	Override the API base URL (default https://api.orcatrace.dev).

---

Disclaimer

OrcaTrace provides informational prediction-market data and analysis aggregated from public sources. Whale calibration measures entries held to resolution, not trader P&L. Nothing here is financial advice, and everything is provided as-is without warranty. See https://api.orcatrace.dev/terms.txt.

Docs for agents: https://api.orcatrace.dev/llms.txt · full: https://api.orcatrace.dev/llms-full.txt

---

License

MIT © jcislo