# OrcaTrace API — Full Agent Reference (v1.0.0)

> Extended reference: every endpoint with full description, parameters, and an example JSON
> body. Compact version: https://api.orcatrace.dev/llms.txt · OpenAPI: https://api.orcatrace.dev/openapi.json

## Base URL & discovery surface
- API base: https://api.orcatrace.dev
- /llms.txt (compact) · /llms-full.txt (this) · /discovery (JSON enumeration)
- /openapi.json (OpenAPI 3.1) · /.well-known/x402 · /.well-known/agent-card.json
- Payment: x402 V2 · Networks: eip155:8453 · Asset: USDC · Scheme: exact

## GET /v1/index   (FREE)
Free (rate-limited 5/min per IP). Current Polymarket feed index — poll target to detect new items (cadence ~10min).

Rate limit: 5/min.

Example response:
```json
{
  "success": true,
  "status": "live",
  "index": 1044,
  "lastUpdated": "2026-07-09T20:00:00.000Z",
  "totalToday": 37,
  "todayByType": {
    "mover": 21,
    "whale_entry": 12,
    "predetermined": 4
  },
  "feedTypes": [
    "mover",
    "whale_entry",
    "predetermined"
  ],
  "digest": {
    "latestAt": "2026-07-09T20:00:00.000Z",
    "title": "US-Iran Diplomacy Repricing Drives the Board"
  }
}
```

## GET /v1/pulse   (FREE)
Free (rate-limited 5/min per IP). Top-3 Polymarket repricings (24h, noise-filtered) plus a digest teaser — the hook.

Rate limit: 5/min.

Example response:
```json
{
  "success": true,
  "status": "live",
  "topMovers24h": [
    {
      "question": "Will the next US-Iran meeting be in Switzerland?",
      "window": "24h",
      "priceStart": 0.07,
      "priceNow": 0.57,
      "delta": 0.5,
      "liquidityUsd": 39715
    }
  ],
  "digestTitle": "US-Iran Diplomacy Repricing Drives the Board",
  "digestAt": "2026-07-09T20:00:00.000Z"
}
```

## GET /v1/digest/brief   (FREE)
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.

Example response:
```json
{
  "success": true,
  "data": {
    "title": "US-Iran Diplomacy Repricing Drives the Board",
    "summary": "A 50-point repricing on the Switzerland meeting market leads an otherwise quiet day…",
    "sourcesUsed": [
      "polymarket",
      "news"
    ],
    "createdAt": "2026-07-09T20:00:00.000Z"
  }
}
```

## GET /v1/sample   (FREE)
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.

Example response:
```json
{
  "success": true,
  "_notice": {
    "type": "sample",
    "message": "Static samples of every paid response shape. Live data via the paid endpoints."
  },
  "feedItems": [
    {
      "feedIndex": 1042,
      "type": "mover",
      "title": "Will the next US-Iran meeting be in Switzerland?"
    }
  ]
}
```

## GET /v1/track-record   (FREE)
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.

Example response:
```json
{
  "success": true,
  "computedAt": "2026-07-09T20:00:00.000Z",
  "coverage": {
    "trackedWallets": 128,
    "resolvedEntries": 41230,
    "labeledWallets": 96
  },
  "overall": {
    "holdToResolutionWinRate": 0.312,
    "followRoiCostWeighted": -0.11,
    "fadeRoiCostWeighted": 0.14
  },
  "topWallets": [
    {
      "pseudonym": "Domer",
      "wallet": "0x9d84ce0306f8551e02efef1680475fc0f1dc1344",
      "resolvedEntries": 912,
      "winRate": 0.082,
      "label": "fade"
    }
  ]
}
```

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

Settlement: compute-first.

Example response:
```json
{
  "success": true,
  "status": "live",
  "data": {
    "feedIndex": 1044,
    "type": "predetermined",
    "title": "Will Contestant X win Season 4 of The Masked Singer?",
    "createdAt": "2026-07-09T19:05:00.000Z",
    "data": {}
  },
  "charged": true
}
```

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

Parameters:
- `index` (integer, query, optional) — Feed index of the item to fetch. Omit for latest.

Settlement: compute-first.

Example response:
```json
{
  "success": true,
  "data": {
    "feedIndex": 1042,
    "type": "mover",
    "title": "Will the next US-Iran meeting be in Switzerland?",
    "createdAt": "2026-07-09T18:40:00.000Z",
    "data": {}
  },
  "charged": true
}
```

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

Parameters:
- `since` (integer, query, optional) — Feed index to fetch items after (poll pattern).
- `count` (integer, query, optional) — Max items (1-20, default 10).
- `type` (string, query, optional) — Filter: mover, whale_entry, or predetermined.

Settlement: compute-first.

Example response:
```json
{
  "success": true,
  "count": 1,
  "filters": {
    "since": 1000,
    "count": 10,
    "type": "all"
  },
  "data": [
    {
      "feedIndex": 1042,
      "type": "mover",
      "title": "Will the next US-Iran meeting be in Switzerland?",
      "createdAt": "2026-07-09T18:40:00.000Z",
      "data": {}
    }
  ],
  "charged": true
}
```

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

Settlement: compute-first.

Example response:
```json
{
  "success": true,
  "data": {
    "id": "clx0digest123",
    "title": "US-Iran Diplomacy Repricing Drives the Board",
    "summary": "A 50-point repricing on the Switzerland meeting market leads an otherwise quiet day…",
    "fullAnalysis": "## What Moved and Why\n…(400-800 words)…",
    "sourcesUsed": [
      "polymarket",
      "news"
    ],
    "createdAt": "2026-07-09T20:00:00.000Z"
  },
  "charged": true
}
```

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

Parameters:
- `hours` (integer, query, optional) — Lookback window in hours (1-168).
- `limit` (integer, query, optional) — Max digests to return (1-42).

Settlement: compute-first.

Example response:
```json
{
  "success": true,
  "count": 1,
  "hours": 24,
  "data": [
    {
      "id": "clx0digest123",
      "title": "US-Iran Diplomacy Repricing Drives the Board",
      "summary": "…",
      "createdAt": "2026-07-09T20:00:00.000Z"
    }
  ],
  "charged": true
}
```

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

Parameters:
- `withinHours` (integer, query, optional) — Horizon in hours (1-72).
- `minLiquidity` (number, query, optional) — Liquidity floor in USD (>=1000).
- `includeNoise` (string, query, optional) — Set to 1 to include mechanical short-interval markets.

Settlement: settle-early.

Example response:
```json
{
  "success": true,
  "count": 1,
  "filters": {
    "withinHours": 24,
    "minLiquidity": 5000,
    "includeNoise": false
  },
  "data": [
    {
      "question": "Will X happen by June 14?",
      "eventEndDate": "2026-06-14T00:00:00Z",
      "hoursRemaining": 22.5,
      "yesMid": 0.83,
      "convergence": "contested",
      "liquidityUsd": 41000
    }
  ]
}
```

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

Settlement: settle-early.

Example response:
```json
{
  "success": true,
  "data": {
    "wallets": [
      {
        "pseudonym": "Domer",
        "wallet": "0x9d84ce0306f8551e02efef1680475fc0f1dc1344",
        "resolved": 912,
        "winRate": 0.082,
        "fadeRoi": 0.209,
        "label": "fade"
      }
    ]
  }
}
```

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

Parameters:
- `market` (string, query, required) — Polymarket market slug (from polymarket.com/market/<slug>).

Settlement: settle-early.

Example response:
```json
{
  "success": true,
  "cached": false,
  "data": {
    "market": {
      "question": "Will the next US-Iran meeting be in Switzerland?",
      "slug": "next-us-iran-meeting-switzerland"
    },
    "analysis": {
      "thesis": "…",
      "whaleView": "…",
      "risks": [
        "…"
      ],
      "confidence": "medium",
      "bottomLine": "…"
    }
  }
}
```

## Payment
Strictly pay-per-call. An unpaid paid-route request returns a 402 challenge whose accepts[] lists one exact USDC rail per network (Base). Sign one rail and retry with PAYMENT-SIGNATURE (x402 V2) or X-PAYMENT (legacy).