# orcatrace-mcp

MCP server for **[OrcaTrace](https://orcatrace.dev)** — 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)

```json
{
  "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**:

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

The paid tools then settle each call automatically.

### Install snippets

Claude Code:

```bash
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](https://x402.org) `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