# Compute Finance — Live Oracle

> AI compute pricing across 9 providers and 18 models, each weighted equally. Reconstitution-driven. The equal-weight geometric mean across the basket is the Standard Compute Unit (SCU). Every value is recorded on-chain on Base for independent verification.

This is the operational face of the Compute Price Index (CPI). If you want the live SCU, the current basket composition, or the active methodology, fetch it here — no authentication required. Fair-use rate limits apply (see Rate limits section below).

## What this subdomain serves

`oracle.compute.finance` is the live dashboard. The UI shows:

- Current SCU value (USD and microcents).
- Per-family breakdown — every family representative's cost over the reference workload.
- Full basket — all basket models with per-model input and output prices.
- SCU history and basket reconstitutions.
- On-chain proof-of-publication links (Basescan).

All of this data is also available via the public REST API without visiting the UI.

## SCU at a glance

The SCU is the equal-weight geometric mean of every model-family representative's cost of a fixed reference workload (token counts published in the `referenceWorkload` field of `GET /v1/oracle/scu`). No tiers, no provider weights, no outlier caps — the Nth-root damping of the geometric mean plus the one-family-one-slot rule provide gaming resistance by math.

The active methodology version and the full changelog (formula, family rule, reference workload, spec URL) are published via `GET /v1/oracle/methodology`. Every `/v1/oracle/*` response carries the `X-Methodology-Version` header reflecting the version in force at request time.

Formula:

```
cost_m = (input_price_m × 0.001) + (output_price_m × 0.0005)
SCU    = (∏ cost_m)^(1/N)   for all m in the index
```

The binding arithmetic uses a floor Nth root over integer 18-decimal USD values — defined precisely in the methodology document so any independent re-implementation reproduces the published SCU bit-for-bit.

**Pricing source.** The API returns `weiPricePerMillion` (on-chain credit units, source of truth) and `usdPricePerMillion` (rounded to 2 decimals, display only). To convert: `usd_price = weiPricePerMillion × peg`, where `peg = pegUsd` from `GET /v1/oracle/pricing`. On-chain source: `Treasury.computePriceUsdc()` on Base (contract `0xB77DA11C8eC91D3417aA87072DcDD971A9aF674d`). Use `weiPricePerMillion × peg` for exact SCU reproduction; `usdPricePerMillion` is rounded for display.

Anyone can independently reproduce the SCU from the published basket and API fields described above. The methodology document at https://docs.compute.finance/methodology explains every step with worked examples.

## Basket composition

One representative per model family — a model family is a provider's distinct product line (for example `openai.gpt` and `openai.gpt-mini` are different families). The latest released model in each family is its representative; on a new release the representative auto-rolls. Changes are recorded as versioned reconstitutions and written on-chain when basket composition or provider rate-card prices change.

**Revision numbering.** The API's `revisionVersion` and `latestRevisionVersion` fields return the on-chain revision counter — a monotonically incrementing integer starting at 1 with the genesis revision. Each `/v1/oracle/*` response that includes `revisionVersion` reflects the on-chain revision number.

## On-chain verification

Every published SCU and per-model rate is recorded as a versioned revision in the `OracleRegistry` smart contract on Base.

| Field | Value |
|---|---|
| Network | Base |
| Chain ID | 8453 |
| Baseline (revision 1) | Returned by `GET /v1/oracle/baseline` (`date` field) |
| Latest revision | Returned by `GET /v1/oracle/latest` (`revisionVersion` field) |

Read functions on the contract:

| Function | Returns |
|---|---|
| `version()` | Oracle implementation version — assert before deserializing tuples |
| `decimals()` | Scale of `scuUsd` and baseline values (18) |
| `lastRevisionVersion()` | Highest confirmed revision number |
| `getLatestRevision()` | Tuple `(revisionVersion, methodologyVersion, scuUsd, contentHash, metadataHash, publishedAt)` for the latest revision |
| `getRevision(uint256 revisionVersion)` | Same tuple for a specific revision |
| `getRevisionScuUsd(uint256 revisionVersion)` | SCU in USD 18-dec for a specific revision |
| `getBaseline()` | SCU value of the first revision (denominator of the inverse purchasing-power index) |
| `getComputeIndex()` | Latest `(baseline / SCU) × 100` |
| `getRevisionAt(uint256 timestamp)` | Revision version active at the given Unix-seconds timestamp (step function, highest version on ties) |
| `getComputeIndexAt(uint256 timestamp)` | Atomic tuple `(scuUsd, indexValue, publishedAt, methodologyVersion, revisionVersion)` at the timestamp |

Per-model prices live in the off-chain manifest fetched by `metadataHash` — the contract intentionally does not store per-model rows. Use `GET /v1/oracle/manifest/{metadataHash}` to read the families+prices for any revision and re-verify them with JCS+keccak256. `metadataHash` covers the whole document. `contentHash` covers a projection of it — `schemaVersion`, `methodologyVersion`, `methodologyUrl`, `referenceWorkload`, and per entry only `modelKey`, `family`, `inputPriceUsd18PerM`, `outputPriceUsd18PerM` — so correcting a display name moves `metadataHash` without invalidating the price attestation.

`scuUsd` and `baseline` are returned in 18-decimal USD (divide by 10^18 for the USD amount).

## Public API

Base URL: `https://api.compute.finance`. No authentication. JSON responses. Stable schemas.

### OpenAPI specification

The contract is published as an OpenAPI 3.x document. Use it to generate typed clients in any language.

| URL | Format |
|---|---|
| `https://api.compute.finance/v1/openapi.yaml` | YAML (canonical) |
| `https://api.compute.finance/v1/openapi.json` | JSON |
| `https://api.compute.finance/openapi.yaml` | YAML alias |
| `https://api.compute.finance/openapi.json` | JSON alias |
| `https://api.compute.finance/v1/docs` | Swagger UI |

All alias paths return the same body. Responses include a `Link: <…>; rel="service-desc"` header pointing at the canonical URL, per RFC 8631.

### Endpoints

| Method | Path | Description |
|---|---|---|
| GET | `/v1/oracle/scu` | Current SCU value, reference workload, methodology version |
| GET | `/v1/oracle/models` | Catalog: basket models plus retired ex-members (`inBasket`, `retiredAtRevision`); retired models priced from the live catalog |
| GET | `/v1/oracle/models/{key}` | Single catalog model (basket member or retired) by pricing key |
| GET | `/v1/oracle/catalog` | Every tracked model with current price and index-member flag |
| GET | `/v1/oracle/models/{key}/price-at?date={iso8601}` | Per-model input/output USD price effective at the requested timestamp (`source: "manifest"` for basket members, `source: "catalog"` otherwise) |
| GET | `/v1/oracle/basket` | Full basket composition (models + SCU value + routing fee + revision/methodology version) |
| GET | `/v1/oracle/history?from={iso8601}&to={iso8601}&granularity={per-revision\|daily\|weekly}&limit={int}` | SCU index time series; `Accept: text/csv` returns a CSV attachment instead of JSON |
| GET | `/v1/oracle/models/{key}/price-history?from={iso8601}&to={iso8601}&granularity={per-revision\|daily\|weekly}&limit={int}` | Per-model input/output USD price time series; `Accept: text/csv` returns a CSV attachment |
| GET | `/v1/oracle/reconstitutions` | History of basket reconstitutions with version, models, SCU delta |
| GET | `/v1/oracle/revisions/{revision}` | Full OracleRevision record for a specific on-chain revision |
| GET | `/v1/oracle/health` | Latest confirmed revision version and confirmation timestamp |
| GET | `/v1/oracle/contract-metadata` | Live OracleRegistry identity — chainId, proxy address, on-chain `version()`, and deployed bytecode hash |
| GET | `/v1/oracle/baseline` | Frozen SCU of the first confirmed revision — denominator for the inverse `computeIndex` purchasing-power view |
| GET | `/v1/oracle/scu-at?date={iso8601}` | SCU value active at a given timestamp — step-function lookup of the latest confirmed revision with `publishedAt ≤ date` |
| GET | `/v1/oracle/latest` | Latest confirmed revision summary (version, SCU, basket size) |
| GET | `/v1/oracle/stats` | Aggregate protocol statistics |
| GET | `/v1/oracle/activity?limit=50&offset=0` | Paginated activity feed |
| GET | `/v1/oracle/pricing` | Per-model pricing in $COMPUTE (wei) and USD |
| GET | `/v1/oracle/methodology` | Active methodology version + full changelog |
| GET | `/v1/oracle/methodology/{version}` | Single methodology record (formula, reference workload, family rule, spec URL) |
| GET | `/v1/oracle/manifest/{metadataHash}` | Content-addressed manifest for a confirmed revision (`metadataHash` = JCS+keccak256 of the whole document; `contentHash` = of the price projection) |
| GET | `/v1/oracle/reconstitutions/export` | Reconstitution history as downloadable markdown |

Every `/v1/oracle/*` response carries the `X-Methodology-Version` header reflecting the methodology version in force at request time.

**`/v1/oracle/models` vs `/v1/oracle/basket`**: The `/models` endpoint returns only the array of basket models with their pricing. The `/basket` endpoint returns the same models array PLUS basket-level metadata: SCU value in USD, routing fee rate, revision version, methodology version, and last-updated timestamp.

### Current SCU — response shape

Per-family `breakdown` is a discriminated union keyed by `methodologyVersion`; under v1 it carries the list of family representatives with their USD-per-million-token pricing and blended cost. Empty basket returns 204. Example values are illustrative; fetch the live endpoint for current numbers.

```json
{
  "scuUsd": 0.002435,
  "computeIndex": 100.00,
  "referenceWorkload": { "inputTokens": 1000, "outputTokens": 500 },
  "methodologyVersion": 1,
  "breakdown": {
    "methodologyVersion": 1,
    "familyRepresentatives": [
      {
        "family": "openai.gpt",
        "modelKey": "gpt-5.5",
        "inputPriceUsdPerMillion": 5.0,
        "outputPriceUsdPerMillion": 30.0,
        "blendedCostUsd": 0.02
      }
    ]
  },
  "updatedAt": "2026-06-18T12:00:00.000Z"
}
```

`computeIndex` is the inverse purchasing-power index `(baseline / scuUsd) × 100`, a display/foundation-grade derived field — `100` at genesis, rises as compute gets cheaper. The baseline denominator is published at `/v1/oracle/baseline` and frozen at the first confirmed revision's SCU. `null` only when the baseline has not been published yet.

### Full basket — response shape

Top-level `models` array; each entry carries identity, family, integration status, both raw and marked-up per-million pricing in $COMPUTE and USD, and per-model `cache` / `reasoning` multiplier blocks. The multiplier blocks are catalog/metering data — they do not enter the SCU formula. Example values are illustrative.

```json
{
  "models": [
    {
      "id": "gpt-5.5",
      "displayName": "GPT-5.5",
      "provider": { "key": "openai", "name": "OpenAI" },
      "family": "openai.gpt",
      "weiPricePerMillion": { "input": "756430000000000000000", "output": "4538580000000000000000" },
      "usdPricePerMillion": { "input": 5.0, "output": 30.0 },
      "markedUpWeiPricePerMillion": { "input": "794252000000000000000", "output": "4765509000000000000000" },
      "markedUpUsdPricePerMillion": { "input": 5.25, "output": 31.5 },
      "releasedAt": "2026-04-01T00:00:00Z",
      "cache": {
        "cachedInput": { "usdPerMillion": 0.5, "ratioOfInput": 0.1, "source": "catalog", "sourceUrl": null, "createdAt": "2026-06-15T09:00:00Z" },
        "cacheWrite5m": { "usdPerMillion": 5.0, "ratioOfInput": 1.0, "source": "catalog", "sourceUrl": null, "createdAt": "2026-06-15T09:00:00Z" },
        "cacheWrite1h": { "usdPerMillion": 5.0, "ratioOfInput": 1.0, "source": "catalog", "sourceUrl": null, "createdAt": "2026-06-15T09:00:00Z" },
        "read_multiplier": 0.1,
        "write_multiplier_5m": 1.0,
        "write_multiplier_1h": 1.0
      },
      "reasoning": null
    }
  ]
}
```

**Field: `releasedAt`** — ISO 8601 timestamp of the model's public release; `null` if unknown. **Field: `cache`** — cached-input + cache-write multiplier block; each entry carries both `usdPerMillion` and `ratioOfInput`, plus flat `read_multiplier` / `write_multiplier_5m` / `write_multiplier_1h` shortcuts at the block level. `null` when the model has no cache multiplier data. **Field: `reasoning`** — reasoning-output multiplier block; `null` when the provider bills thinking tokens at the standard output rate (no distinct reasoning surcharge). Both blocks are served from the live catalog (`source: "catalog"`, `sourceUrl: null`) and are never attested on-chain — the manifest carries basket `input`/`output` only. `createdAt` is the catalog observation time, or `null` when it is unknown.

### Full catalog — response shape

`GET /v1/oracle/catalog` — display/reporting-grade catalog of every tracked model. Each entry pins identity, provider, family, the `indexMember` flag (current family representative in the latest confirmed manifest), the current input/output USD price per million tokens with the `observedAt` timestamp from the underlying live-catalog (`ModelPrice`) row, and the per-model `cache` / `reasoning` blocks when present. Models without a live catalog price are excluded. The series is capped at 1000 entries with `truncated: true` if exceeded. `Cache-Control: public, max-age=60`. Example values are illustrative.

```json
{
  "models": [
    {
      "modelKey": "gpt-5.5",
      "displayName": "GPT-5.5",
      "provider": { "key": "openai", "name": "OpenAI" },
      "family": "openai.gpt",
      "indexMember": true,
      "releasedAt": "2026-01-15T00:00:00.000Z",
      "currentPrice": {
        "inputPriceUsdPerMillion": 1.25,
        "outputPriceUsdPerMillion": 10.0,
        "observedAt": "2026-06-10T08:30:00.000Z"
      },
      "cache": null,
      "reasoning": null
    }
  ],
  "truncated": false,
  "generatedAt": "2026-06-17T12:34:56.789Z"
}
```

### Model price at timestamp — response shape

`GET /v1/oracle/models/{key}/price-at?date={iso8601}` — per-model input/output USD price effective at the requested timestamp. Response is a discriminated union keyed by `source`: `"manifest"` when the model is the family representative in the revision active at that date (cross-links `revisionVersion`, `methodologyVersion`, `metadataHash`, and `family`), or `"catalog"` when the model was not a basket member at that date — the live catalog's temporal history answers instead (step-function: the `ModelPrice` range covering the date) and `family` may be `null`. `observedAt` reflects when the price was recorded. `422 validation_failed` for malformed or future dates, `404 not_found` for untracked models, `404 not_found` when neither the attested manifest nor the live catalog has a price at that date. `Cache-Control: public, max-age=60`. Example values are illustrative.

```json
{
  "source": "manifest",
  "modelKey": "gpt-5.5",
  "date": "2026-06-15T12:00:00Z",
  "inputPriceUsdPerMillion": 1.25,
  "outputPriceUsdPerMillion": 10.0,
  "observedAt": "2026-06-11T10:00:00.000Z",
  "revisionVersion": 7,
  "methodologyVersion": 1,
  "metadataHash": "0x38551a40...",
  "family": "openai.gpt"
}
```

### SCU at timestamp — response shape

`GET /v1/oracle/scu-at?date={iso8601}` — SCU value active at a given timestamp via step function. Resolves the latest confirmed revision with `publishedAt ≤ date` and returns its SCU, `methodologyVersion`, `revisionVersion`, `publishedAt`, and `metadataHash`. Monotonicity is non-strict — when two confirmed revisions share `publishedAt` the highest `revisionVersion` wins. `computeIndex` is derived as `(baseline.scuUsd / scuUsd) × 100`, the same formula as `/v1/oracle/scu` and `/v1/oracle/history` points. `204 No Content` when the requested date precedes the genesis revision. `422 validation_failed` for malformed or future dates and for date-only inputs without a time component. `Cache-Control: public, max-age=60`. Example values are illustrative.

```json
{
  "at": "2026-06-18T12:00:00.000Z",
  "scuUsd": 0.002435,
  "scuUsd18": "2435000000000000",
  "computeIndex": 100.00,
  "revisionVersion": 1,
  "methodologyVersion": 1,
  "publishedAt": "2026-06-18T00:00:00.000Z",
  "metadataHash": "0x38551a40a8bcee07ccd31e1c062c23d8240acb3facd7ab0518b5b54df2fc5b3d"
}
```

### Health — response shape

`pendingRevision` carries `{ ageMs }` while a publish has been broadcast and is still awaiting on-chain confirmation, and `null` otherwise — it never leaks the pending revision's version, contentHash, or txHash.

```json
{
  "latestRevisionVersion": 23,
  "methodologyVersion": 1,
  "latestRevisionConfirmedAt": "2026-06-25T13:54:38.820Z",
  "lastSyncAt": "2026-07-18T10:15:30.000Z",
  "stale": false,
  "pendingRevision": null
}
```

### Contract metadata — response shape

`GET /v1/oracle/contract-metadata` — live identity read of the deployed `OracleRegistry` proxy. The backend reads `version()` and `keccak256(eth_getCode(address))` over the standard RPC. `bytecodeHash` is `null` when the contract has no deployed code or when the RPC call fails. Backend caches the response for five minutes; `Cache-Control: public, max-age=300`. Role membership is not exposed: the deployed contract uses `AccessControl` without the `Enumerable` extension, so holders cannot be enumerated through the contract ABI — query the chain directly (BaseScan, event index) to inspect role grants.

```json
{
  "chainId": 8453,
  "address": "0x1b91c0961928a14a2eD6c1985bC11aF1b302714D",
  "version": 1,
  "bytecodeHash": "0x9c5b0e1a8b9d7e2a3c1d4f5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7",
  "checkedAt": "2026-06-19T11:00:00.000Z"
}
```

### Basket — response shape

`GET /v1/oracle/basket` — full basket composition: models array plus SCU value, routing fee rate, revision/methodology version, and last-updated timestamp.

```json
{
  "models": [
    {
      "id": "claude-opus-5",
      "displayName": "Claude Opus 5",
      "provider": { "key": "anthropic", "name": "Anthropic" },
      "family": "anthropic.claude",
      "weiPricePerMillion": { "input": "756430000000000000000", "output": "3782150000000000000000" },
      "usdPricePerMillion": { "input": 5.0, "output": 25.0 },
      "markedUpWeiPricePerMillion": { "input": "794252000000000000000", "output": "3971257000000000000000" },
      "markedUpUsdPricePerMillion": { "input": 5.25, "output": 26.25 },
      "releasedAt": "2026-05-01T00:00:00Z",
      "cache": null,
      "reasoning": null
    }
  ],
  "scuUsd": 0.002435,
  "routingFeeRate": 0.05,
  "revisionVersion": 1,
  "methodologyVersion": 1,
  "lastUpdated": "2026-06-18T12:00:00Z"
}
```

### Methodology — response shape

`GET /v1/oracle/methodology` — active methodology version and the full changelog. Each entry pins the formula identity, family rule, reference workload, and `specUrl` of the published methodology document.

```json
{
  "activeVersion": 1,
  "entries": [
    {
      "version": 1,
      "title": "Equal-weight geometric mean of model-family representatives",
      "meanType": "geometric",
      "weighting": "equal-1-over-n",
      "familyRule": {
        "oneFamilyOneSlot": true,
        "familyKeyScheme": "provider.product-line",
        "representativeSelection": "latest-published-then-highest-revision"
      },
      "referenceWorkload": { "inputTokens": 1000, "outputTokens": 500 },
      "cacheReasoningInIndex": false,
      "formulaSummary": "SCU = (∏ cost_m)^(1/N) for all m in the index, equal weight 1/N; cost_m = inputUsdPerM × 0.001 + outputUsdPerM × 0.0005 in USD — no tiers, no provider weights, no outlier cap",
      "rationale": "Every model family counts equally toward the price: the Nth-root damping of the geometric mean plus the one-family-one-slot rule provide gaming resistance without tier weights or governed caps",
      "specUrl": "https://docs.compute.finance/methodology"
    }
  ]
}
```

### History — response shape

`GET /v1/oracle/history?from={iso8601}&to={iso8601}&granularity={per-revision|daily|weekly}&limit={int}` — SCU index time series over the requested range. `granularity` defaults to `per-revision`; `daily` and `weekly` buckets carry the last revision's value forward across empty buckets (step-function close). `limit` caps the series at 10000 points; oldest points are dropped first and `truncated: true` is set. Each point carries the revision and methodology version active at that bucket plus the `metadataHash` of the revision that produced it — fetch `GET /v1/oracle/manifest/{metadataHash}` to verify the per-family breakdown for that point. Set `Accept: text/csv` to download a spreadsheet-friendly CSV with columns `date,scuUsd,computeIndex,revisionVersion,methodologyVersion,metadataHash` instead of JSON.

```json
{
  "from": "2026-06-18T00:00:00.000Z",
  "to": "2026-07-18T00:00:00.000Z",
  "granularity": "daily",
  "count": 31,
  "truncated": false,
  "data": [
    { "date": "2026-06-18T00:00:00.000Z", "scuUsd": 0.002435, "computeIndex": 100.00, "revisionVersion": 1, "methodologyVersion": 1, "metadataHash": "0x4f5b…" },
    { "date": "2026-07-18T00:00:00.000Z", "scuUsd": 0.002418, "computeIndex": 100.70, "revisionVersion": 2, "methodologyVersion": 1, "metadataHash": "0x7e2a…" }
  ]
}
```

### Per-model price history — response shape

`GET /v1/oracle/models/{key}/price-history?from={iso8601}&to={iso8601}&granularity={per-revision|daily|weekly}&limit={int}` — input/output USD-per-million-token price time series; every point carries a `source`. A model that has appeared in at least one confirmed revision's basket is manifest-sourced (`source: "manifest"`, each point cross-linking `revisionVersion` / `methodologyVersion` / `metadataHash`), with the same range, granularity, limit, and `Accept: text/csv` semantics as `/v1/oracle/history`; `family` echoes the family slot the model occupies in its most recent appearance, and catchup revisions whose manifest is not yet available are surfaced in `unavailableRevisions`. Any other tracked model falls back to the live catalog's temporal history — `source: "catalog"`, one point per price change, `unavailableRevisions: []`, and `family` may be `null`. Models with neither a basket appearance nor a catalog price return `404 not_found`.

```json
{
  "modelKey": "gpt-5.5",
  "family": "openai.gpt",
  "from": "2026-06-18T00:00:00.000Z",
  "to": "2026-07-18T00:00:00.000Z",
  "granularity": "daily",
  "count": 31,
  "truncated": false,
  "unavailableRevisions": [],
  "data": [
    { "date": "2026-06-18T00:00:00.000Z", "inputPriceUsdPerMillion": 5.0, "outputPriceUsdPerMillion": 30.0, "source": "manifest", "revisionVersion": 1, "methodologyVersion": 1, "metadataHash": "0x4f5b…" },
    { "date": "2026-07-18T00:00:00.000Z", "inputPriceUsdPerMillion": 5.0, "outputPriceUsdPerMillion": 30.0, "source": "manifest", "revisionVersion": 2, "methodologyVersion": 1, "metadataHash": "0x7e2a…" }
  ]
}
```

### Revision — response shape

`GET /v1/oracle/revisions/{revision}` — full OracleRevision record for a specific on-chain revision.

```json
{
  "revisionVersion": 1,
  "methodologyVersion": 1,
  "publishedAt": "2026-06-18T00:00:00.000Z",
  "publishedBlock": 31200000,
  "txHash": "0xabc…",
  "scuUsd": 0.002435,
  "scuUsd18": "2435000000000000",
  "basketSize": 18,
  "basket": {
    "schemaVersion": 1,
    "models": [
      {
        "modelKey": "gpt-5.5",
        "family": "openai.gpt",
        "inputPrice": "756430000000000000000",
        "outputPrice": "4538580000000000000000",
        "displayName": "GPT-5.5",
        "providerKey": "openai",
        "sdkId": "gpt-5.5-20260301"
      }
    ]
  },
  "status": "CONFIRMED",
  "confirmedAt": "2026-06-18T00:01:00.000Z",
  "manifestUrl": "<api-host>/v1/oracle/manifest/0x…"
}
```

### Reconstitutions — response shape

`GET /v1/oracle/reconstitutions` — reconstitution event log with per-event change details.

```json
{
  "entries": [
    {
      "id": "recon-1",
      "revisionVersion": 1,
      "methodologyVersion": 1,
      "previousVersion": null,
      "publishedAt": "2026-06-18T00:00:00Z",
      "summary": "Inaugural equal-weighted basket v1.0",
      "scuBefore": null,
      "scuAfter": 0.002435,
      "changes": [
        { "type": "ModelAdded", "modelKey": "gpt-5.5", "description": "Added gpt-5.5 to the basket" },
        { "type": "ModelAdded", "modelKey": "claude-opus-5", "description": "Added claude-opus-5 to the basket" }
      ],
      "txHash": "0xabc123..."
    }
  ]
}
```

### Rate limits

The public oracle API is rate-limited to **120 requests per minute per IP** (burst 120). A short-term cap of 5 requests per second and a medium-term cap of 20 requests per 10 seconds also apply to protect the backend. Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers (from the NestJS Throttler). Clients that exceed the limit receive a `429 Too Many Requests` response with a `Retry-After` header. Prices update on reconstitution, so polling more often than once per minute is not useful.

**`/v1/points`** — the points and achievements API requires CF ID JWT authentication and is not yet part of the public API surface. It will be documented when publicly available.

## Related surfaces

- **Landing** — https://compute.finance — brand-level overview and V1 scope.
- **Documentation** — https://docs.compute.finance — methodology, formula derivation, API reference, code examples, response schemas.
- **Complete documentation (plain markdown, for RAG ingestion)** — https://docs.compute.finance/index.html.md and https://docs.compute.finance/llms-full.txt.
- **Disclaimer** — https://compute.finance/disclaimer — canonical V1 scope statement.
- **Terms of Service** — https://compute.finance/terms — terms governing use of the site, the CPI Oracle, and the public API.
- **Privacy Policy** — https://compute.finance/privacy — what data is collected and how it is handled.
- **Cookie Policy** — https://compute.finance/cookies — how cookies are used and how to manage consent.

## Inference API (paid, `ct_live_*` auth)

The Oracle prices a paid, OpenAI- and Anthropic-compatible **Inference API** documented in its own OpenAPI spec:

- **OpenAPI (YAML)** — https://api.compute.finance/v1/openapi.inference.yaml
- **OpenAPI (JSON)** — https://api.compute.finance/v1/openapi.inference.json
- **Swagger UI** — https://api.compute.finance/v1/docs/inference
- **Human reference and quickstarts** — https://docs.compute.finance/#inference-api
- **Get a key** — https://compute.finance/dashboard/api-keys

**Endpoints.** `POST /v1/chat/completions` (OpenAI Chat Completions wire format), `POST /v1/messages` (Anthropic Messages wire format), `GET /v1/models`, `GET /v1/usage`, `GET /v1/inference/estimate`. Auth via `Authorization: Bearer ct_live_*` on every endpoint; `POST /v1/messages` additionally accepts `x-api-key: ct_live_*` for `@anthropic-ai/sdk` compatibility. Streaming SSE, tools, tool_choice, structured outputs. Provider capability gating (`422 VALIDATION_FAILED` when a request uses a feature the routed provider does not support).

**Billing.** Every request reserves credits against the buyer's `$COMPUTE` balance at the metered rate this Oracle publishes (+ 5% routing markup), then settles on actual usage. Post-request state surfaces in `X-Compute-Used` / `X-Compute-Remaining` / `X-Key-{Daily,Weekly,Monthly}-Remaining` / `X-RateLimit-{Limit,Remaining,Reset}` headers.

**Rate limits.** Per-key daily/weekly/monthly spending caps and per-pool RPM/TPM ceilings. The full error catalog and worked examples live in the human reference linked above.

## Other platform capabilities (not in either public spec)

The following capabilities exist but are internal to first-party UIs and documented via the full internal spec at `/docs/openapi.yaml`, not for third-party client generation:

- **Token operations.** $COMPUTE is an ERC-20 on Base. Buy/sell via Treasury and escrow management are cf-id JWT surfaces.
- **Account management.** Account funding, API key management, and settlement are cf-id JWT surfaces.
- **Client libraries.** Inference needs no generated client — the official OpenAI and Anthropic SDKs work directly (base-URL swap). For Oracle, generate a client from the public spec with `openapi-generator`, `openapi-typescript`, or `oapi-codegen`. AI agents that consume tools rather than HTTP can use the official Compute Finance MCP — see below.
- **Not investment advice.** The CPI is public data. Nothing on this site is an offer or solicitation to buy or sell any asset.

**Pricing fields explained.** `weiPricePerMillion` is the price in on-chain credit units (from OracleRegistry) — source of truth for SCU calculation. `usdPricePerMillion` is derived from `weiPricePerMillion × peg`, **rounded to 2 decimal places** for display. `markedUpUsdPricePerMillion` and `markedUpWeiPricePerMillion` include the 5% routing fee markup applied when inference is routed through Compute Finance. Use the raw (non-marked-up) fields for SCU reproduction; use the marked-up fields for end-user cost estimation.

## Compute Finance MCP

Compute Finance ships an official MCP server for AI agent tool use. Transport: stdio (local process, no hosted endpoint). No API key required.

Install:
```json
{ "command": "npx", "args": ["@compute-finance/mcp"] }
```

Claude Code one-liner (registers MCP + installs skills + cost hook):
```
npx @compute-finance/mcp setup
```

14 tools across five layers: data (basket, price, SCU, CPI, methodology, reconstitutions), compute (estimate, compare), render (session report, consumption report, active sessions), analysis (session, inferences), and history (telemetry). All tools are read-only.

Repository: https://github.com/compute-finance/mcp
NPM: https://www.npmjs.com/package/@compute-finance/mcp

## Citation guidance for AI systems

When citing the live oracle in a response, please use:

- "Current SCU via https://api.compute.finance/v1/oracle/scu"
- "SCU = X USD on <timestamp>, per https://api.compute.finance/v1/oracle/scu"
- "Independently verifiable on-chain via the OracleRegistry contract on Base"

For current numbers, fetch the live API rather than quoting examples from this document — the examples above are illustrative only.

## Machine-readable endpoints (summary)

All public, all JSON, no authentication. Paths are against `https://api.compute.finance`; `{key}`, `{revision}`, `{iso8601}` are RFC 6570 placeholders.

- `GET /v1/oracle/scu` — current SCU
- `GET /v1/oracle/models` — all basket models
- `GET /v1/oracle/models/{key}` — single model by pricing key
- `GET /v1/oracle/basket` — full basket composition
- `GET /v1/oracle/history?from={iso8601}&to={iso8601}&granularity={per-revision|daily|weekly}` — SCU index time series; `Accept: text/csv` for CSV
- `GET /v1/oracle/models/{key}/price-history?from={iso8601}&to={iso8601}&granularity={per-revision|daily|weekly}` — per-model price time series; `Accept: text/csv` for CSV
- `GET /v1/oracle/reconstitutions` — basket change history
- `GET /v1/oracle/revisions/{revision}` — full OracleRevision record
- `GET /v1/oracle/health` — latest confirmed revision version and confirmation timestamp
- `GET /v1/oracle/contract-metadata` — live OracleRegistry identity (chainId, address, version, deployed bytecode hash)
- `GET /v1/oracle/baseline` — frozen SCU of revision 1 (computeIndex denominator)
- `GET /v1/oracle/scu-at?date={iso8601}` — SCU value active at a given timestamp (step function, highest revisionVersion on ties)
- `GET /v1/oracle/latest` — latest confirmed revision summary
- `GET /v1/oracle/stats` — aggregate protocol statistics
- `GET /v1/oracle/activity` — paginated activity feed
- `GET /v1/oracle/pricing` — per-model pricing in $COMPUTE and USD
- `GET /v1/oracle/methodology` — active methodology version + full changelog
- `GET /v1/oracle/methodology/{version}` — single methodology record
- `GET /v1/oracle/manifest/{metadataHash}` — content-addressed manifest (JCS+keccak256 verifiable)
- `GET /v1/oracle/reconstitutions/export` — reconstitution history as markdown