# OrcaTrace API

OrcaTrace — Polymarket intelligence on x402. Track smart money, see what others miss. Real-time prediction-market signals across 42K markets: quality-gated repricings with order-book microstructure, tracked-whale entries annotated with each wallet's hold-to-resolution calibration (follow/fade), and AI-detected predetermined-outcome markets — one unified, index-polled feed. The whale track record is verifiable and free: the /v1/track-record scorecard 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-chain before paying. Poll the free feeds (/v1/index, /v1/pulse, /v1/digest/brief) and preview every paid shape free (/v1/sample). Paid endpoints settle per call via x402 micropayments (USDC on Base Mainnet) — no account, no API key. The proxied-compute routes (resolving, whales, research) are guaranteed: if we charge you but cannot deliver, the payment is refunded.

- **Base URL**: https://api.orcatrace.dev
- **Docs (agent-facing)**: https://api.orcatrace.dev/llms.txt · https://api.orcatrace.dev/llms-full.txt
- **OpenAPI 3.1**: https://api.orcatrace.dev/openapi.json
- **Discovery (JSON)**: https://api.orcatrace.dev/discovery
- **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

Polymarket intelligence — informational, provided as-is, not investment, financial, or trading advice.

## Free (no auth, no payment)

| Method | Path | What |
|--------|------|------|
| GET | /health | Liveness + payment mode |
| 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) |
| GET | /terms.txt · /terms.json | Terms of Service |

## Paid (x402 V2 — USDC on eip155:8453, per-call)

| Method | Path | Price | What |
|--------|------|-------|------|
| 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. |

Prices are USD, settled as USDC (6 decimals). The DB-read routes are compute-first / settle-after
(never charged for errors). The proxied-compute routes (resolving, whales, research) settle early
but are guaranteed: a non-delivery refunds your payment.

## Quickstart — pay per call (x402, USDC)

```
# 1) Call a paid route with no payment → 402 challenge
curl -s "https://api.orcatrace.dev/v1/latest"
# → { "x402Version": 2, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "USDC",
#     "price": "$0.01", "payTo": "0x…" } ], "terms": "https://api.orcatrace.dev/terms.txt" }

# 2) Sign an x402 'exact' USDC authorization for one accepts[] rail, then retry.
#    Standard @x402 V2 clients send PAYMENT-SIGNATURE; legacy clients send X-PAYMENT.
curl -s "https://api.orcatrace.dev/v1/latest" -H "PAYMENT-SIGNATURE: <payload>"
# → 200 { …, "charged": true }
```

## 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