<!--
Hosts:
  https://mpp.oculr.xyz   API canonical host - POST /explain, /explain/async, GET /result/:jobId, /openapi.json, /tool-spec.json, /SKILL.md, /llms*.txt, /health
  https://oculr.xyz       Docs site + human-facing web app (/docs, /app)

Sitemap:
- [oculr](/): AI-powered EVM transaction analysis API across 50+ EVM mainnets (chain auto-detected from tx hash). Submit a tx hash, receive a structured explanation with summary, txType, confidence, addresses, risks, and (when triaging) broken-invariant findings.
- [Introduction](/docs/): Overview of oculr, who it's for, the MPP/x402 payment model, metered pricing, and endpoints at a glance.
- [Pricing](/docs/pricing): Metered pricing - formula (cost × 1.20 + $0.02), real production examples, model cost tradeoffs, spend caps, cost transparency.
- [FAQ](/docs/faq): Metered pricing, chains table, transactions, agents, and troubleshooting.
- [Quickstart overview](/docs/quickstart/): Choose your integration path - agent CLI, your own code, or the web app.
- [Use as an agent](/docs/quickstart/agent): Three integration modes - Skill mode (one-shot prompt or persistent install), Tool-use mode (typed `/tool-spec.json`), Raw API.
- [Call the oculr MPP](/docs/quickstart/client): Make your first paid /explain request in under 5 minutes using mppx for automatic MPP payment handling.
- [Analyze a transaction](/docs/guides/analyzing-transactions): Submit a tx hash and interpret the structured result - enum tables, partial-result handling, txType routing, confidence branching.
- [Use the web app](/docs/guides/web-app): Human-facing UI at oculr.xyz/app - wallet connect, MPP session payment, the five result views.
- [Core concepts](/docs/concepts/): Three-phase analysis pipeline (pre-flight → agent loop → report), MPP/x402 sessions, confidence levels, partial results, sync vs async.
- [Under the hood](/docs/concepts/under-the-hood): How oculr buys traces, labels, prices, web research, and compute over MPP per request - the self-funding supply chain.
- [Glossary](/docs/concepts/glossary): Canonical definitions for ExplanationResult, txType, confidence, MPP, mppx, Tempo, USDC.e, and all other terms used across the docs.
- [Endpoints overview](/docs/reference/endpoints): Table of all endpoints with links to the per-endpoint pages and response-header reference.
- [POST /explain](/docs/reference/endpoints/explain): Synchronous analysis - request schema, full ExplanationResult shape, SSE streaming, error codes (400, 402, 500, 502).
- [POST /explain/async](/docs/reference/endpoints/explain-async): Non-blocking variant - request schema, 202 response, error codes.
- [GET /result/:jobId](/docs/reference/endpoints/result): Async polling - request, response shape, polling loop, error codes (404).
- [GET /health](/docs/reference/endpoints/health): Service health probe (free).
- [Discovery surfaces](/docs/reference/endpoints/discovery): /openapi.json, /tool-spec.json, /SKILL.md, /llms.txt, /llms-full.txt (all free).
- [OpenAPI spec](https://mpp.oculr.xyz/openapi.json): Machine-readable OpenAPI 3.1 - partial-result contract, 402 challenge schema, securityScheme=mpp.
- [Tool-use spec](https://mpp.oculr.xyz/tool-spec.json): Anthropic + OpenAI tool-call schemas - drop-in replacement for hand-written tool descriptors when wiring oculr into a sub-agent.
- [SKILL.md](https://mpp.oculr.xyz/SKILL.md): One-fetch agent instructions for autonomous coding agents.
- [llms-full.txt](https://mpp.oculr.xyz/llms-full.txt): Auto-generated full doc corpus.
- [Health check](https://mpp.oculr.xyz/health): GET /health - status, version.
-->

# oculr

> AI-powered EVM transaction analysis API across 50+ EVM mainnets (auto-detected from tx hash). Designed for agent consumption - JSON by default, async-first, MPP/x402 autonomous payment, partial-synthesis fallback so subagents never see a 5xx.

**API canonical host: `https://mpp.oculr.xyz`** (MPP/x402 paid endpoints). Docs and the human-facing web app live at `https://oculr.xyz`.

oculr analyses transactions on 50+ EVM mainnets - Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, Avalanche, and many more. Chain is auto-detected from the tx hash - no `chain` field in the request needed. The pipeline fetches on-chain data, decodes calldata and events, resolves addresses and entities, and produces a structured report. Payment is per-request via MPP/x402 (no API key, settled in USDC.e on Tempo via MPP sessions).

## Pricing

Metered: `charge = upstream cost × 1.20 + $0.02`, settled in $0.01 voucher increments as the analysis runs. Typical analyses on the default model (`claude-opus-4-8`) cost $0.45-$0.90; simple transfers less, complex incident investigations more. Pass a cheaper `model` on the request body (`claude-sonnet-4-6`, `claude-haiku-4-5-20251001`) to cut the dominant LLM cost component. Full details: https://oculr.xyz/docs/pricing

Every response carries a `costs` object with category buckets (`llms`, `dataCollection`, `codeExecution`, `other`) and a `totalUsd` summing them.

## Subagent contract (read this if you are a parent agent)

oculr is designed to be called from inside an LLM agent loop. The conventions that matter:

- **Agent default is async.** `POST /explain/async` + poll `GET /result/:jobId` (1 h TTL) - fixed quote per request, plain `fetch()` with the `Mppx.create()` polyfill works. Sync `POST /explain` is a metered SSE stream requiring `tempo.session.manager().sse()`; plain JSON `POST /explain` returns `402` with `code: "use_metered_sse"`.
- **The server never 5xx's mid-analysis.** When an upstream service fails, you get HTTP 200 with `confidence: 'low'` and a `summary` starting with `**Partial result`. Always check `confidence` and the "Partial result" summary header before trusting the body.
- **`context` (≤2 KB) steers the agent.** To opt into structured exploit findings (`findings[]` with `broken_invariant`, `category`, `severity`), pass `context: "Triage this transaction for exploit-shaped activity per /SKILL.md"`.
- **Costs are always attached.** `body.costs.totalUsd` is set even on partial results - no need to optional-chain. The parent agent's cost-tracking shouldn't have a null branch.
- **Idempotency is keyed on the payment nonce** (`channelId:amount`), not the URL. Re-submitting the same call on the same payment voucher is safe.
- **`Link` response header** lists `/SKILL.md`, `/openapi.json`, `/tool-spec.json` as `rel="describedby"` (RFC 5988). One header gives you all three discovery surfaces.
- **MPP/x402 payment is required.** You need an MPP-capable client (the `mppx` npm package handles the 402 challenge transparently); a Bearer-only HTTP client can read free endpoints but cannot call `/explain*`.

## Endpoints

| Method | Path | Auth | Purpose |
|---|---|---|---|
| `POST` | `/explain` | MPP | Synchronous analysis |
| `POST` | `/explain/async` | MPP | Non-blocking - returns `jobId` |
| `GET` | `/result/:jobId` | free | Poll an async job |
| `GET` | `/health` | free | Service health probe |
| `GET` | `/openapi.json` | free | OpenAPI 3.1 spec |
| `GET` | `/tool-spec.json` | free | Anthropic + OpenAI tool schemas |
| `GET` | `/SKILL.md` | free | Prose entry point for agents |
| `GET` | `/llms.txt` | free | Discovery index (this file) |
| `GET` | `/llms-full.txt` | free | Full doc corpus |

## Docs

- [Introduction](https://oculr.xyz/docs/): Overview, payment model, metered pricing, endpoints at a glance
- [Pricing](https://oculr.xyz/docs/pricing): Metered formula, real production examples, model cost tradeoffs
- [FAQ](https://oculr.xyz/docs/faq): Metered pricing, chains table, transactions, agents, troubleshooting

## Quickstart

- [Quickstart overview](https://oculr.xyz/docs/quickstart/): Pick agent CLI, your own code, or web app
- [Use as an agent](https://oculr.xyz/docs/quickstart/agent): Skill mode, Tool-use mode (`/tool-spec.json`), Raw API
- [Call the oculr MPP](https://oculr.xyz/docs/quickstart/client): First request in 5 minutes using mppx

## Guides

- [Analyze a transaction](https://oculr.xyz/docs/guides/analyzing-transactions): Full walkthrough - enum tables, partial-result handling, txType routing
- [Use the web app](https://oculr.xyz/docs/guides/web-app): Wallet connect, MPP session payment, the five result views

## Concepts

- [Core concepts](https://oculr.xyz/docs/concepts/): Three-phase pipeline, MPP/x402 sessions, confidence levels, partial results, sync vs async
- [Under the hood](https://oculr.xyz/docs/concepts/under-the-hood): The MPP supply chain - how oculr buys upstream resources per request
- [Glossary](https://oculr.xyz/docs/concepts/glossary): Canonical definitions for every term

## API / Reference

- [Endpoints overview](https://oculr.xyz/docs/reference/endpoints): Per-endpoint pages with request/response/errors
- [POST /explain](https://oculr.xyz/docs/reference/endpoints/explain): Sync analysis - full ExplanationResult schema, SSE streaming, errors
- [POST /explain/async](https://oculr.xyz/docs/reference/endpoints/explain-async): Non-blocking - `jobId`, errors
- [GET /result/:jobId](https://oculr.xyz/docs/reference/endpoints/result): Polling - status transitions, errors
- [GET /health](https://oculr.xyz/docs/reference/endpoints/health): Health probe
- [Discovery surfaces](https://oculr.xyz/docs/reference/endpoints/discovery): `/openapi.json`, `/tool-spec.json`, `/SKILL.md`, `/llms*.txt`
- [OpenAPI spec](https://mpp.oculr.xyz/openapi.json): Machine-readable OpenAPI 3.1
- [Tool-use spec](https://mpp.oculr.xyz/tool-spec.json): Anthropic + OpenAI tool-call schemas

## Optional

- [SKILL.md](https://mpp.oculr.xyz/SKILL.md): One-fetch agent instructions - setup, core tasks (sync + async + health), verification, troubleshooting, pricing table
- [llms-full.txt](https://mpp.oculr.xyz/llms-full.txt): Auto-generated full doc corpus
- [Health check](https://mpp.oculr.xyz/health): GET /health - returns status, version