# OrcaTrace API — Polymarket intelligence for AI agents on x402 — whale tracking with a verifiable track record, signals, the 4-hourly Intelligence Digest, resolving-market analysis, and $1 deep research. Per-call, no signup. Track smart money, see what others miss. (v1.0.0)

> OrcaTrace is a pay-per-call Polymarket-intelligence API for AI agents. Track smart money, see what others miss. It serves real-time prediction-market signals across 42K markets: quality-gated repricings with order-book microstructure, tracked-whale entries with hold-to-resolution calibration (follow/fade), and predetermined-outcome signals — plus the 4-hourly Intelligence Digest, markets resolving soon, and on-demand single-market deep research. The whale track record is verifiable and FREE at /v1/track-record. Poll the free feeds (/v1/index, /v1/pulse, /v1/digest/brief) and preview every paid response shape free (/v1/sample) before paying. Paid endpoints settle per call via x402 (USDC on Base).

## Base URL
- API: https://api.orcatrace.dev
- This document: https://api.orcatrace.dev/llms.txt  ·  Extended: https://api.orcatrace.dev/llms-full.txt
- Discovery (JSON): https://api.orcatrace.dev/discovery
- OpenAPI 3.1: https://api.orcatrace.dev/openapi.json
- x402 manifest: https://api.orcatrace.dev/.well-known/x402
- Agent card (A2A): https://api.orcatrace.dev/.well-known/agent-card.json
- Terms: https://api.orcatrace.dev/terms.txt

## Free endpoints (no auth, no payment)

| Method | Path | Description |
|--------|------|-------------|
| GET | /v1/index | Free (rate-limited 5/min per IP). Current Polymarket feed index — poll target to detect new items (cadence ~10min). (rate limit: 5/min) |
| GET | /v1/pulse | Free (rate-limited 5/min per IP). Top-3 Polymarket repricings (24h, noise-filtered) plus a digest teaser — the hook. (rate limit: 5/min) |
| GET | /v1/digest/brief | Free (rate-limited 5/min per IP). Polymarket Intelligence Digest teaser: title + summary, no analysis. Full digest at GET /v1/digest ($0.10). (rate limit: 5/min) |
| GET | /v1/sample | Free (rate-limited 5/min per IP). Static samples of every paid Polymarket response shape (signal, whales, digest) — explicitly labelled. Use it to learn the contract before paying. (rate limit: 5/min) |
| GET | /v1/track-record | Free (rate-limited 5/min per IP), no auth. Verifiable whale-calibration scorecard (the free proof behind paid /v1/whales): aggregate hold-to-resolution win rate, follow/fade ROI, per-odds-band breakdown, and top-10 wallets with full public addresses. Cross-check every wallet on Polymarket. Measures entries held to resolution, not trader P&L — not financial advice. (rate limit: 5/min) |

## Paid endpoints (x402 V2, USDC on Base, per-call)

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| GET | /v1/latest | $0.01 | Paid ($0.01 USDC via x402). Most recent Polymarket feed item — mover, whale entry (with calibration), or predetermined signal. Same shape as /v1/signal without ?index. Free index poll: GET /v1/index; free shape preview: GET /v1/sample. Compute-first / settle-after — you are never charged for an error. |
| GET | /v1/signal | $0.01 | Paid ($0.01 USDC via x402). One Polymarket feed item: quality-gated mover (vol>=$10k & depth>=$2.5k, +order-book microstructure), whale entry (named whale, with calibration + microstructure), or predetermined signal. Use ?index=N for a specific item, omit for latest. Compute-first / settle-after — you are never charged for an error. |
| GET | /v1/signals | $0.03 | Paid ($0.03 USDC via x402). Batch Polymarket feed items (up to 20): quality-gated movers + order-book microstructure, whale entries with calibration, predetermined signals. Poll GET /v1/index (free), then ?since=N for new items; filter with &type=mover\|whale_entry\|predetermined. Compute-first / settle-after — you are never charged for an error. |
| GET | /v1/digest | $0.1 | Paid ($0.10 USDC via x402). Polymarket Intelligence Digest (every 4h): what repriced and why across 42K markets — significant moves, whale positioning interpreted through calibration, predetermined-outcome signals, and international news context. Synthesized analysis, not raw data. Never serves stale: returns 503 if generation falls behind (no charge). Compute-first / settle-after — you are never charged for an error. |
| GET | /v1/digest/history | $0.05 | Paid ($0.05 USDC via x402). Historical Polymarket Intelligence Digests (up to 7 days, 4h cadence) — track how prediction-market narratives evolved: ?hours=24&limit=6. Compute-first / settle-after — you are never charged for an error. |
| GET | /v1/resolving | $0.02 | Paid ($0.02 USDC via x402). Markets resolving within ?withinHours (1-72): odds, contested-vs-converged, liquidity, and order-book microstructure for the nearest expiries. Mechanical short-interval markets excluded by default (?includeNoise=1 to include). Settle-early with a guaranteed refund — if we charge you but cannot deliver, the payment is refunded. |
| GET | /v1/whales | $0.05 | Paid ($0.05 USDC via x402). Whale calibration table: per-wallet hold-to-resolution win rates by odds band, mirror/fade ROI, and follow/fade labels (min 30 resolved entries). The data behind the whale_entry annotations in the signal feed; the free proof is GET /v1/track-record. Settle-early with a guaranteed refund — if we charge you but cannot deliver, the payment is refunded. |
| GET | /v1/research | $1 | Paid ($1.00 USDC via x402). Single-market deep-dive: 7-day price action + live order book + tracked-whale positioning with calibration + related international news, synthesized into a thesis with risks and an actionable bottom line. Generated on demand (10-60s); cached 30 minutes. Use ?market=<slug> from polymarket.com/market/<slug> or from our feed items. Settle-early with a guaranteed refund — if we charge you but cannot deliver, the payment is refunded. |

## How to pay (x402)
Each paid call answers a 402 challenge; sign an x402 `exact` USDC authorization for one advertised rail (Base) and retry. Standard @x402 V2 clients send the `PAYMENT-SIGNATURE` header; legacy clients send `X-PAYMENT`. Prices are USD, settled as USDC (6 decimals).

## Links
- Docs: https://api.orcatrace.dev/llms.txt
- Full: https://api.orcatrace.dev/llms-full.txt
- OpenAPI: https://api.orcatrace.dev/openapi.json
- Discovery: https://api.orcatrace.dev/discovery
- Agent card: https://api.orcatrace.dev/.well-known/agent-card.json
- Website: https://orcatrace.dev

## What OrcaTrace covers
The signal feed unifies three streams. Movers are genuine prediction-market repricings, noise-filtered across 42K markets and quality-gated (volume >= $10k, depth >= $2.5k) with order-book microstructure attached (spread, depth within 5c, USD-impact-to-move). Whale entries are tracked-wallet position entries, each annotated with that wallet's hold-to-resolution calibration — a follow/fade/neutral label computed from resolved, on-chain-auditable positions (>= 30 resolved entries). Predetermined signals are AI-detected markets whose outcome already exists in definitive form (reality-TV results, production-crew knowledge). The Intelligence Digest (every 4 hours) synthesizes what repriced and why — movers, whale flows interpreted through calibration, and international news context. Markets-resolving-soon lists active markets whose event ends within your window with odds/convergence/liquidity/microstructure; single-market research is an on-demand deep-dive thesis for any one market slug.

## Free funnel, verifiable track record & refund guarantee
/v1/index, /v1/pulse, and /v1/digest/brief are live, rate-limited free reads; /v1/sample returns static samples of every paid response shape (explicitly labelled) so you can learn the contract without paying. /v1/track-record is the free, verifiable whale scorecard — the proof behind paid /v1/whales: it publishes the aggregate hold-to-resolution win rate, follow/fade ROI, per-odds-band breakdown, and top wallets with FULL public addresses so a buyer can cross-check any wallet on Polymarket directly before paying. Honest framing (verbatim): calibration measures ENTRIES held to resolution, not trader P&L (exits are not tracked) — informational, not financial advice. The DB-read paid routes are compute-first / settle-after (never charged for a 404/error). The proxied-compute routes (resolving, whales, research) settle early but are GUARANTEED: OrcaTrace verifies + settles, dispatches the compute, and if it charged you but could not deliver a 2xx result, the payment is refunded (a rail-tagged RefundRequest is queued and issued off the public edge).