{
  "openapi": "3.1.0",
  "info": {
    "title": "OrcaTrace API",
    "version": "1.0.0",
    "x-guidance": "OrcaTrace — pay-per-call Polymarket intelligence for AI agents on x402 (USDC on Base Mainnet, eip155:8453). FREE (no key, no payment, rate-limited 5/min per IP): GET /v1/index (poll target — detect new feed items, ~10min cadence), /v1/pulse (top-3 24h movers + digest teaser), /v1/digest/brief (digest title + summary), /v1/sample (static samples of every paid shape), /v1/track-record (verifiable free whale scorecard — the proof behind paid /v1/whales). PAID (x402): GET /v1/latest ($0.01 — most recent feed item), /v1/signal ($0.01 — one feed item, ?index=N), /v1/signals ($0.03 — batch, poll ?since=N &type=), /v1/resolving ($0.02 — markets resolving soon), /v1/whales ($0.05 — whale calibration table), /v1/digest ($0.10 — full 4-hourly Intelligence Digest), /v1/digest/history ($0.05 — historical digests), /v1/research ($1.00 — single-market deep-dive, ?market=<slug>). Pay flow: call a paid route with no payment -> receive HTTP 402 (the x402 V2 PaymentRequirements ride in the base64 PAYMENT-REQUIRED header; the JSON body mirrors x402Version+accepts) -> sign an EIP-3009 `exact` USDC authorization on Base for the accepts[] amount -> retry the same request with the payment in the PAYMENT-SIGNATURE (V2) or X-PAYMENT (legacy) header. Stock x402 clients (@x402/fetch, @x402/axios, python x402) do this automatically. No accounts or API keys required. The DB-read routes are compute-first / settle-after (never charged for an error); the proxied-compute routes (resolving, whales, research) settle early but are GUARANTEED — a non-delivery refunds your payment.",
    "summary": "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.",
    "description": "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.",
    "termsOfService": "https://api.orcatrace.dev/terms.txt",
    "contact": {
      "name": "OrcaTrace API",
      "url": "https://api.orcatrace.dev"
    }
  },
  "servers": [
    {
      "url": "https://api.orcatrace.dev",
      "description": "OrcaTrace API public edge"
    }
  ],
  "externalDocs": {
    "description": "Agent-facing reference (llms.txt)",
    "url": "https://api.orcatrace.dev/llms.txt"
  },
  "tags": [
    {
      "name": "free",
      "description": "No auth, no payment."
    },
    {
      "name": "paid",
      "description": "x402 V2 per-call pricing (USDC on eip155:8453)."
    }
  ],
  "paths": {
    "/v1/index": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "polymarket-index",
        "summary": "Polymarket feed index",
        "description": "Free (rate-limited 5/min per IP). Current Polymarket feed index — poll target to detect new items (cadence ~10min).",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/pulse": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "polymarket-pulse",
        "summary": "Polymarket top-3 movers brief",
        "description": "Free (rate-limited 5/min per IP). Top-3 Polymarket repricings (24h, noise-filtered) plus a digest teaser — the hook.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/digest/brief": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "polymarket-digest-brief",
        "summary": "Polymarket digest teaser",
        "description": "Free (rate-limited 5/min per IP). Polymarket Intelligence Digest teaser: title + summary, no analysis. Full digest at GET /v1/digest ($0.10).",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/sample": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "polymarket-sample",
        "summary": "Polymarket sample shapes",
        "description": "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.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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?"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/track-record": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "polymarket-track-record",
        "summary": "Whale-calibration scorecard",
        "description": "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.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/latest": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "polymarket-latest",
        "summary": "Most recent Polymarket feed item ($0.01)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "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.",
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/v1/signal": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "polymarket-signal",
        "summary": "One Polymarket feed item ($0.01)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "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": [
          {
            "name": "index",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Feed index of the item to fetch. Omit for latest."
          }
        ],
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/v1/signals": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "polymarket-signals",
        "summary": "Batch Polymarket feed items ($0.03)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.030000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "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": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Feed index to fetch items after (poll pattern)."
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            },
            "description": "Max items (1-20, default 10)."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter: mover, whale_entry, or predetermined."
          }
        ],
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/v1/digest": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "polymarket-digest",
        "summary": "Polymarket Intelligence Digest ($0.1)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "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.",
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/v1/digest/history": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "polymarket-digest-history",
        "summary": "Historical Polymarket digests ($0.05)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.050000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "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": [
          {
            "name": "hours",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 168,
              "default": 24
            },
            "description": "Lookback window in hours (1-168)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 42,
              "default": 6
            },
            "description": "Max digests to return (1-42)."
          }
        ],
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/v1/resolving": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "polymarket-resolving",
        "summary": "Markets resolving soon ($0.02)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "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": [
          {
            "name": "withinHours",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 72,
              "default": 24
            },
            "description": "Horizon in hours (1-72)."
          },
          {
            "name": "minLiquidity",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 1000,
              "default": 5000
            },
            "description": "Liquidity floor in USD (>=1000)."
          },
          {
            "name": "includeNoise",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Set to 1 to include mechanical short-interval markets."
          }
        ],
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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
                      }
                    ]
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/v1/whales": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "polymarket-whales",
        "summary": "Whale calibration table ($0.05)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.050000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "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.",
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "success": true,
                    "data": {
                      "wallets": [
                        {
                          "pseudonym": "Domer",
                          "wallet": "0x9d84ce0306f8551e02efef1680475fc0f1dc1344",
                          "resolved": 912,
                          "winRate": 0.082,
                          "fadeRoi": 0.209,
                          "label": "fade"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/v1/research": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "polymarket-research",
        "summary": "Single-market deep-dive research ($1)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "1.000000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "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": [
          {
            "name": "market",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Polymarket market slug (from polymarket.com/market/<slug>)."
          }
        ],
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "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": "…"
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "PaymentRequired": {
        "description": "x402 V2 payment challenge. Sign an `exact` USDC authorization for one accepts[] rail, then retry with the PAYMENT-SIGNATURE (V2) or X-PAYMENT (legacy) header. You are not charged for errors or below-threshold answers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PaymentRequired"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "x402": {
        "type": "http",
        "scheme": "x402",
        "description": "Custom HTTP 402 payment flow (x402 V2). The server answers an unpaid paid-route request with a 402 whose body is a PaymentRequired envelope (x402Version + accepts[] + terms). Each accepts[] entry is an `exact`-scheme USDC rail. Sign ONE rail and retry the same request with the `PAYMENT-SIGNATURE` header (x402 V2 clients) or the legacy `X-PAYMENT` header. Per-call pricing."
      }
    },
    "schemas": {
      "PaymentRequired": {
        "type": "object",
        "description": "x402 V2 PaymentRequired envelope. accepts[] lists one exact USDC rail per network.",
        "properties": {
          "x402Version": {
            "type": "integer",
            "const": 2
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": {
                  "type": "string",
                  "const": "exact"
                },
                "network": {
                  "type": "string",
                  "enum": [
                    "eip155:8453"
                  ]
                },
                "asset": {
                  "type": "string",
                  "const": "USDC"
                },
                "price": {
                  "type": "string",
                  "description": "USD price string."
                },
                "payTo": {
                  "type": "string",
                  "description": "Settlement address for this rail."
                },
                "mimeType": {
                  "type": "string",
                  "const": "application/json"
                }
              }
            }
          },
          "terms": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}