# Orrery — Full Technical Reference for LLMs and Agents

> Decision terminal for prediction markets (orrery.me). Polymarket-first, multi-venue planned. Live, public, no signup.

This document is the comprehensive machine-readable reference. The shorter
human-friendly version lives at `/llms.txt`. The OpenAPI spec lives at
`/openapi.yaml` and `/.well-known/openapi.yaml`. The agent discovery
manifest lives at `/.well-known/ai-plugin.json`.

---

## 1. Identity and positioning

Orrery is a public, read-only intelligence terminal that aggregates,
normalises, and explains live data from Polymarket. Its design centre is a
daily workflow:

- morning Daily Brief with biggest moves, unusual volume, signals,
  resolution risk;
- intraday alerts on user-defined rules;
- per-market terminal pages explaining *why* probabilities moved.

Orrery is not affiliated with Polymarket and does not facilitate trading.
It does not provide investment, legal, tax, betting, or trade advice. Research
only. Not trade advice.

---

## 2. Routes

Surface area as of 2026-06-08.

| Path | Type | Purpose |
|---|---|---|
| `/` | Page | Home Command Center: Top Actions, Market Pulse, Daily Brief, Resolution Risk, Watchlist, and trust-state context. |
| `/scanner` | Page | Dense markets table with search grammar, URL-synced sort, resolution countdown. |
| `/markets/[slug]` | Dynamic page | Per-market terminal: chart, recent trades, holders, signals, AI "Why it moved", resolution risk, related markets, timeline. |
| `/markets/category/[slug]` | Dynamic page | Category-filtered scanner with category-specific framing. |
| `/signals` | Page | Observation feed with Evidence / Historical support / Action tiers. |
| `/opportunities` | Page | Research Queue: ranked verification candidates with confidence, risk, horizon, and recommended next step. |
| `/whales` | Page | $10k+ trade feed from the Data API. |
| `/wallets` | Page | Wallet activity leaderboard with sample-confidence and activity-is-not-profitability guardrails. |
| `/wallets/[address]` | Dynamic page | Wallet activity, concentration, sample confidence, and risk context. |
| `/portfolio` | Page | Read-only multi-wallet aggregation. |
| `/watchlist` | Page | Tracked markets with since-last-visit deltas. |
| `/alerts` | Page | User-defined rules. |
| `/copilot` | Page | Free-text AI research grounded in live snapshot. |
| `/backtest` | Page | Historical signal performance. |
| `/pricing` | Page | Customer-facing plans for analysts, teams, and agents who need verified market context. |
| `/receipts` | Page | Public market receipts plus aggregate x402 usage ledger: attempts, 402 challenges, settled calls, and top paid endpoints. |
| `/for/analysts` | Page | Audience answer page for analysts looking for a prediction-market intelligence platform. |
| `/for/journalists` | Page | Audience answer page for journalists monitoring market-moving prediction-market stories. |
| `/for/research-teams` | Page | Audience answer page for shared research-team verification workflows. |
| `/for-newsletters` | Page | Audience answer page for Daily Brief and newsletter workflows. |
| `/for-agents`, `/for/ai-agents` | Page | AI-agent workflow pages for APIs, MCP, x402, Decision Cards, and free starter routes. |
| `/api/prediction-market-api` | Page | Public answer page for the Orrery prediction market API. |
| `/api/polymarket-api-for-agents` | Page | Public answer page for Polymarket-first API workflows for AI agents. |
| `/research` | Page | Research Library: evergreen prediction-market verification guides. |
| `/research/[slug]` | Static page | Pillar guides on observations, resolution risk, wallet context, and agent APIs. |
| `/research/[slug]/markdown` | Text | Clean text version of each Research Library guide for source-grounded citation. |
| `/research/rss.xml` | Feed | RSS 2.0 feed of Research Library guides. |
| `/brief` | Page | Daily brief landing + email subscription. |
| `/brief/personal` | Page | Browser-local personal brief from watchlist, alerts, and tracked wallets. No account, no upload, noindex. |
| `/brief/archive` | Page | Index of past briefs. |
| `/brief/archive/[date]` | Dynamic page | A specific day's brief. |
| `/brief/rss.xml` | Feed | RSS 2.0 of recent briefs. |
| `/status` | Page | Live HTTP probes of every upstream. |
| `/docs/agents/demos` | Page | Copy/paste x402 use-case demos for monitoring, resolution risk, move explanations, watchlists, and attention queues. |
| `/docs/agents/sdk` | Page | Installable TypeScript and Python SDK package docs for x402 agents, plus local verification commands. |
| `/rooms` | Page | Per-market discussion preview. |
| `/disclaimer`, `/terms`, `/privacy`, `/contact` | Page | Legal + contact. |
| `/openapi.yaml`, `/.well-known/openapi.yaml` | YAML | Machine-readable API spec. |
| `/.well-known/ai-plugin.json` | JSON | Agent discovery manifest. |
| `/.well-known/security.txt` | Text | Security contact. |
| `/llms.txt`, `/llms-full.txt` | Text | This document and its summary. |
| `/knowledge-graph.jsonld` | JSON-LD | Static knowledge graph (FAQ + entities). |
| `/sitemap.xml` | XML | Includes top markets + all static routes. |
| `/robots.txt` | Text | Allows all major search engines and AI crawlers. |

---

## 2a. Research Library corpus

Orrery's `/research` library is designed for durable search and answer-engine
retrieval. Every post has:

- canonical HTML at `/research/{slug}`;
- Article + FAQ JSON-LD on first render;
- clean text version at `/research/{slug}/markdown`;
- sitemap entry for both HTML and clean text;
- internal links into live product pages and methodology.

Current pillar posts:

| Path | Primary intent |
|---|---|
| `/research/prediction-market-verification-layer` | "prediction market verification layer", "price is not settlement", "trust-state transitions" |
| `/research/prediction-market-signals` | "prediction market observations", "Polymarket signals" |
| `/research/polymarket-resolution-risk` | "Polymarket resolution risk", "Polymarket resolution rules" |
| `/research/polymarket-whale-tracking` | "Polymarket whale tracker", "large trade context" |
| `/research/prediction-market-api-for-ai-agents` | "prediction market API", "x402 API", "AI agent market data" |
| `/research/best-polymarket-analytics-tools` | "best Polymarket analytics tools", "prediction market dashboard" |
| `/research/how-to-track-polymarket-whales` | "how to track Polymarket whales", "wallet tracking" |
| `/research/how-polymarket-markets-resolve` | "how Polymarket markets resolve", "settlement rules" |
| `/research/prediction-market-api-for-agents` | "prediction market API for agents", "agentic market data" |
| `/research/polymarket-signals-explained` | "Polymarket signals explained", "signal families" |
| `/research/polymarket-vs-kalshi-data` | "Polymarket vs Kalshi data", "prediction market data" |
| `/research/election-prediction-markets` | "election prediction markets", "political market odds" |
| `/research/crypto-prediction-markets` | "crypto prediction markets", "Bitcoin prediction markets" |
| `/research/what-is-x402` | "what is x402", "HTTP 402 payments" |
| `/research/build-ai-agent-prediction-markets` | "build AI agent prediction markets", "x402 agent API" |

---

## 2b. Audience and API answer pages

Orrery has dedicated answer pages for recurring discovery questions that
answer engines and search crawlers often ask before choosing a product page.

| Path | Questions answered |
|---|---|
| `/for/analysts` | best prediction market analytics tools; best Polymarket analytics tools; prediction market intelligence platform; tools to monitor Polymarket markets. |
| `/for/journalists` | tools for journalists monitoring prediction markets; how to monitor market-moving events on Polymarket; tools to understand why a prediction market moved; prediction market daily brief. |
| `/for/research-teams` | prediction market verification layer; verification-first prediction market tool; shared prediction-market monitoring for research teams. |
| `/for-newsletters` | prediction market daily brief; Polymarket alerts and signals tool; newsletter-ready market context. |
| `/for-agents` and `/for/ai-agents` | prediction market API for AI agents; AI agent API for prediction market data; MCP; x402; Decision Cards. |
| `/api/prediction-market-api` | prediction market API for AI agents; best API for Polymarket data; Orrery prediction market API. |
| `/api/polymarket-api-for-agents` | Polymarket API for AI agents; Polymarket data API context; how to verify Polymarket resolution risk through an API workflow. |

These pages are canonical public routes with WebPage + FAQPage JSON-LD,
internal links into live product surfaces, and research-only boundaries.

---

## 3. Public APIs

All endpoints are CORS-enabled (`Access-Control-Allow-Origin: *`).

### `GET /api/markets?slugs=a,b,c`
Batch market lookup. Returns `{ markets: OrreryMarket[], fetchedAt: ISO8601 }`.
Up to 50 slugs per request. Cached `s-maxage=30, stale-while-revalidate=60`.

### `GET /api/search?q=<text>`
Live market full-text search. Returns up to 20 results matching question /
category / slug. Used by the command palette.

### `GET /api/wallets?address=<0x…>`
Returns `{ address, positions, activity, pseudonym, fetchedAt }`. Address
must be a valid Ethereum address. Cached `s-maxage=60`.

### `POST /api/explain`
Streaming "why did it move?" explanation. Body shape:
```json
{
  "slug": "string",
  "question": "string",
  "category": "string",
  "price": 0.0,
  "priceChange1h": 0.0,
  "priceChange24h": 0.0,
  "priceChange1w": 0.0,
  "volume24h": 0.0,
  "liquidity": 0.0,
  "spread": 0.0,
  "endDate": "ISO8601 | null",
  "umaResolutionStatus": "string | null",
  "trades": [
    { "side": "BUY|SELL", "outcome": "Yes|No", "usdValue": 0, "price": 0, "timestamp": 0, "pseudonym": "string|null" }
  ]
}
```
Returns `text/plain` chunked stream. Header
`x-orrery-explain-source: claude-sonnet-4-6 | heuristic` exposes the
generation backend. When the backend can't reach Claude, the route falls
back to a deterministic summary from the supplied metrics.

### `POST /api/copilot`
Streaming free-text Q&A. Body: `{ question: string }`. Server fetches a
fresh data snapshot (top 60 markets + active signals + summary) and
provides it to the model as the user message. System prompt enforces:
- ground every claim in the supplied data;
- cite specific market questions and numbers;
- never predict future direction;
- refuse "insider info" requests;
- redirect off-topic questions.

### `POST /api/brief/subscribe`
Subscribe an email to the Daily Brief. Body: `{ email, source }`.

### `POST /api/brief/deliver`
Cron-triggered delivery. Auth via `Authorization: Bearer ${CRON_SECRET}`.
When `RESEND_API_KEY` is set, sends to all subscribers; otherwise returns a
dry-run response.

### `POST /api/waitlist`
Generic waitlist capture for non-brief features. Body: `{ email, source }`.

---

## 3a. Free starter API

Orrery exposes a capped no-auth starter API for agent and developer first touch:

- `/api/free/v1/catalog` — endpoint list plus the free/paid boundary.
- `/api/free/v1/health` — upstream and catalog health.
- `/api/free/v1/brief/preview` — limited Daily Brief preview.
- `/api/free/v1/markets/movers` — capped live-research top movers.
- `/api/free/v1/markets/search?q=...` — capped market search.
- `/api/free/v1/markets/{slug}/snapshot-lite` — compact market snapshot.

Use this layer for discovery. Deep explanations, resolution-risk analysis,
wallet profiles, share cards, decision bundles, and agent-ready paid payloads
remain under x402/API credits.

---

## 3b. Competitive Positioning and comparison map

Orrery's competitive map starts at `/compare` and expands into dedicated pages
such as `/compare/polymarketscan`, `/compare/polywhaler`,
`/compare/verso`, `/compare/dome-polyrouter`, `/compare/eventgraph`,
`/compare/polyedge-ai`, `/compare/orcalayer`, and
`/compare/dune-polymarket-dashboards`. These pages define the category
boundary:

- Orrery is not an execution terminal.
- Orrery is not a copy-trading product.
- Orrery is not a raw data vendor.
- Orrery is the verification-first intelligence layer: status, source context,
  resolution risk, Daily Brief, alerts, and agent-readable Decision Cards.

Core claims: price is not settlement; high evidence is not edge; large trade is
not smart money; same event is not the same contract; raw data is not
interpreted intelligence.

Current comparison coverage:

| Page | Main question answered |
|---|---|
| `/compare/polymarketscan` | Orrery vs PolymarketScan; alternatives to PolymarketScan; Polymarket analytics and whale tracking. |
| `/compare/polywhaler` | Orrery vs PolyWhaler; alternatives to PolyWhaler; large-trade and wallet context. |
| `/compare/polymarket-analytics` | Trader analytics, hot markets, and cross-venue comparison. |
| `/compare/verso` | Professional prediction-market terminal comparison. |
| `/compare/tremor` | SQL analytics and AI research terminal comparison. |
| `/compare/stand` | Aggregator and execution-terminal comparison. |
| `/compare/dome-polyrouter` | Unified prediction-market API comparison. |
| `/compare/telonex-marketlens` | Historical data and backtesting infrastructure comparison. |
| `/compare/kreo-telegram-bots` | Telegram, wallet-following, and chat-native bot comparison. |
| `/compare/polyseer-predly` | AI research and AI edge-tool comparison. |
| `/compare/polymarket-kalshi` | Native prediction-market venue comparison. |
| `/compare/eventgraph` | EventGraph alternative; Polymarket API, portfolio, order-book, and event intelligence. |
| `/compare/struct` | Struct alternative; Polymarket analytics, market discovery, and news context. |
| `/compare/polyedge-ai` | PolyEdge AI alternative; AI-powered Polymarket analysis and signals. |
| `/compare/probintel` | ProbIntel alternative; prediction-market monitoring and intelligence. |
| `/compare/predict00r` | Predict00r alternative; prediction-market assistant and daily brief use cases. |
| `/compare/orcalayer` | OrcaLayer alternative; Polymarket market data API and infrastructure. |
| `/compare/polyshadow-edgemarket` | Polyshadow / EdgeMarket alternative; whale, flow, and wallet-tracking tools. |
| `/compare/polywatch-polywhale-polytrack` | PolyWatch / PolyWhale / PolyTrack alternative; free whale trackers and large-trade alerts. |
| `/compare/dune-polymarket-dashboards` | Dune Polymarket dashboard alternative for operational verification. |
| `/compare/polyzone-directory` | PolyZone / PolyCatalog tool directory comparison. |
| `/compare/prdictionedge` | PrdictionEdge alternative; AI research and edge scanner comparison. |
| `/compare/manifold-metaculus-predictit` | Adjacent forecasting communities and prediction venues. |

The comparison map is designed to answer broad discovery questions such as
"best Polymarket analytics tools", "Polymarket whale tracking tools",
"prediction market intelligence platform", "prediction market API for AI
agents", "best API for Polymarket data", "how to verify Polymarket resolution
risk", "alternatives to PolymarketScan", and "alternatives to PolyWhaler".

## 3c. Public share artifacts

Orrery's growth loop is shareable verification, not referral spam or trading
hype. Public artifacts are designed for X, LinkedIn, Telegram, Discord, and
agent citations:

- `/share/move/{slug}` — market-move artifact with 24h delta, current
  probability, why/verify sections, and a rich OG image.
- `/share/pulse/{slug}` — 7D market-pulse chart artifact for visual movement
  context.
- `/share/risk/{slug}` — resolution-risk artifact. It turns derived status,
  UMA state, expiry, and source extraction into the message: price is not
  settlement.
- `/whales/trade/{txHash}` — whale-trade receipt. It explains size, market,
  wallet context, and the guardrail: large trade is not smart money.

The artifacts are research-only. They should never imply buy/sell direction,
copying another participant, or certainty about future outcomes.

## 3d. Paid agent API (x402)

The paid agent surface lives under `/api/x402/v1/...`. Discovery files:

- `/pricing` — commercial packaging, use cases, pricing ladder, snippets.
- `/docs/agents` — human docs for x402, MCP, CLI, Python, TypeScript, cURL.
- `/docs/agents/demos` — use-case playbooks with cURL, Python, and TypeScript examples.
- `/docs/agents/sdk` — typed TypeScript and Python SDK package docs.
- `/api/v1/manifest` — free machine-readable manifest with endpoint jobs.
- `/.well-known/x402-services.json` — service catalog with prices.
- `/x402-openapi.yaml` — OpenAPI 3.1 spec.

Production paid endpoints require x402 settlement. Requests without a valid
`X-PAYMENT` proof return HTTP 402 with a JSON challenge. Verified calls return
`payment_status: "settled"`. Free health/catalog/manifest routes remain open.

Aggregate usage telemetry lives at `/api/status/x402-usage` and is summarized
on `/receipts`. It stores counters only: attempts, free/missing/
settled/rate-limited states, quoted USDC, settled USDC, last-seen timestamp, and
per-endpoint totals. It does not persist payer addresses, payment proofs, IPs,
request bodies, or user identifiers.

---

## 4. Data shapes

### `OrreryMarket`
```ts
{
  id: string;
  slug: string;
  question: string;
  price: number;            // YES probability, 0..1
  priceChange1h: number;    // probability delta, raw (not pp)
  priceChange24h: number;
  priceChange1w: number;
  volume: number;           // lifetime USD
  volume24h: number;
  liquidity: number;
  spread: number | null;    // probability points (e.g. 0.02 = 2¢)
  category: string;         // 11 buckets — see §6
  categorySlug: string;
  endDate: string | null;   // ISO 8601
  closed: boolean;
  icon: string | null;
  image: string | null;
  yesTokenId: string | null;
  noTokenId: string | null;
  conditionId: string | null;
  description: string | null;
  resolutionSource: string | null;
  umaResolutionStatus: string | null;
  negRisk: boolean;
  momentumScore: number;    // 0..100 heuristic
  updatedAt: string | null;
}
```

### `OrreryTrade`
```ts
{
  address: string;
  pseudonym: string;
  side: "BUY" | "SELL";
  size: number;
  price: number;            // 0..1
  usdValue: number;
  outcome: string;
  outcomeIndex: number;
  timestamp: number;        // unix seconds
  slug: string;
  title: string;
  icon: string | null;
  txHash: string;
  conditionId: string;
}
```

### `Signal`
```ts
{
  kind: "flow" | "momentum" | "divergence" | "resolution_risk" | "news_lag";
  title: string;
  message: string;
  slug: string;
  question: string;
  category: string;
  confidence: number;       // 0..1, present-time evidence
  factors: string[];
}
```

### `SignalCalibration`
```ts
{
  evidence: "low" | "medium" | "high";
  evidenceScore: number;    // 0..100
  edge: "strong" | "mixed" | "weak" | "forward-only";
  edgeNote: string;
  action: "watch_only" | "inspect_timeline" | "create_alert" | "verify_source" | "ignore";
  actionLabel: string;
}
```

### `Opportunity`
```ts
{
  market: OrreryMarket;
  signals: { signal: Signal, market: OrreryMarket }[];
  edgeScore: number;        // 0..100
  confidence: number;       // 0..100
  capacityEstimate: number; // USD before ~1pp move
  timeHorizonHours: number;
  factors: string[];
  workflow: "watch-closely" | "verify-source" | "create-alert" | "inspect-timeline" | "compare-venues" | "ignore";
}
```

### `WalletScore`
```ts
{
  address: string;
  pseudonym: string | null;
  openPositions: number;
  openNotional: number;
  unrealizedPnl: number;
  realizedPnl: number;
  totalPnl: number;
  roiEstimate: number;
  tradeCount: number;
  avgTradeUsd: number;
  firstSeenAt: number | null;
  lastSeenAt: number | null;
  winRate: number | null;
  winRateSample: number;
  topCategory: string | null;
  categoryConcentration: number;
  qualityScore: number;     // 0..100
  labels: string[];         // e.g. "whale", "profitable specialist"
}
```

---

## 5. Signal taxonomy

| Kind | Trigger | Backtest tier (live) |
|---|---|---|
| `momentum` | 24h \|move\| ≥ 3pp + 1h aligned with 24h + liquidity > 25k | mixed |
| `divergence` | \|1h\| ≥ 1pp moving against 24h, liquidity > 50k | mixed |
| `flow` | 3+ aligned trades in 30min, ≥ $5k clustered, distinct wallets | forward-only |
| `resolution_risk` | <72h to expiry OR UMA non-resolved OR spread > 6¢ near expiry | forward-only |
| `news_lag` | Reserved — needs news ingestion | forward-only |

Each signal carries a 0..1 evidence score plus 1–4 explicit factor strings.

---

## 6. Categories

Orrery's classifier maps each market to one of 11 buckets:
**Crypto · AI · Macro · Geopolitics · Politics · Sports · Weather ·
Entertainment · Science · Business · Tech**. The classifier first uses
Gamma's tag/category if specific, otherwise applies keyword rules in
priority order (specific before broader: AI before Tech, Geopolitics
before Politics).

---

## 7. Resolution source types

Extractor output:
**`exchange_price`** (Binance/Coinbase/CoinGecko spot) ·
**`official_government`** (US gov, White House, agency) ·
**`sports_official_result`** ·
**`court_record`** ·
**`company_filing`** (10-K/Q, SEC filings) ·
**`news_consensus`** (Reuters, AP, WSJ, NYT) ·
**`social_media_post`** ·
**`ambiguous`** (catch-all with low confidence) ·
**`unknown`**.

Each extracted source carries a `confidence: low | medium | high`.

---

## 8. Architecture

Frontend: Next.js 15 App Router, React 19, Tailwind 4, TypeScript strict.
All data fetched server-side from Polymarket's public APIs with 30–300s
revalidation. No separate backend service. Deployed on Vercel.

Watchlist, Alerts, Portfolio, Preferences are stored in `localStorage`
with `useSyncExternalStore` for reactive client-side state.

Plausible analytics — cookieless, no personal data.

---

## 9. Optional integrations (env-keyed)

| Env var | Activates |
|---|---|
| `ANTHROPIC_API_KEY` | Real AI responses on `/api/explain` and `/api/copilot` (claude-sonnet-4-6 with prompt caching). |
| `RESEND_API_KEY` + `BRIEF_FROM` + `CRON_SECRET` | Email delivery of the Daily Brief. |
| `KV_REST_API_URL` + `KV_REST_API_TOKEN` | Persistent subscriber storage. |

Without any keys the site renders fully — every feature degrades to a
deterministic heuristic.

---

## 10. Update cadence

Most server-rendered pages revalidate every 30–60 seconds. The Daily Brief
page revalidates every 5 minutes. Sitemap revalidates hourly. The status
page is `force-dynamic` (live probe on every load).

---

## 11. Bot policy

`/robots.txt` explicitly allows: GPTBot, ChatGPT-User, Claude-Web,
Applebot-Extended, PerplexityBot, Google-Extended, plus the default
`User-agent: *`. We welcome AI crawlers and agent integrations — the
public APIs above are the supported interface.

---

## 12. Contact

| Topic | Email |
|---|---|
| General | hello@orrery.me |
| Privacy / data deletion | privacy@orrery.me |
| Press / partnerships | press@orrery.me |
| Security | security@orrery.me |