# Compute Finance — Live Oracle

> Live AI compute pricing, published hourly. Basket models across major providers weighted into a single reference value — 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, current basket composition, or tier breakdown, 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).
- Tier breakdown — Frontier / Standard / Lightweight contributions.
- Full basket — all basket models with per-model input and output prices.
- Hourly 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

One SCU is the USD cost of a fixed reference workload (token counts published in the `referenceWorkload` field of `GET /v1/oracle/scu`) evaluated across all basket models, weighted by tier, with a 2x outlier cap applied per tier before averaging.

Current tier weights are published via `GET /v1/oracle/tiers`.

Formula (three steps):

```
Step 1  per-model cost       cost_m = input_price_m × input_tokens + output_price_m × output_tokens
Step 2  per-tier capped mean tier_avg_t = mean(min(cost_m, 2 × tier_mean_t))
Step 3  weighted sum         SCU = frontier_avg × frontier_weight + standard_avg × standard_weight + lightweight_avg × lightweight_weight
```

Reference workload token counts: `GET /v1/oracle/scu` (`referenceWorkload` field). Tier weights: `GET /v1/oracle/tiers`.

Anyone with access to provider pricing pages can reproduce this number. The methodology document at https://docs.compute.finance explains every step with worked examples.

## Basket composition

One model per provider per tier. The basket is reviewed quarterly; changes are recorded as versioned reconstitutions and written on-chain.

- **Frontier** — highest-capability models. Best reasoning, longest context.
- **Standard** — balanced cost-performance workhorses.
- **Lightweight** — fastest, cheapest. For high-volume latency-sensitive tasks.

Current tier weights are published via `GET /v1/oracle/tiers`.

Versions:
- **v0** — first deployed June 17, 2025 (internal).
- **v1.0** — public launch April 7, 2026. Carries forward full v0 history.

**Version numbering.** The API's `basketVersion` and `latestRevisionVersion` fields return the on-chain revision counter — a monotonically incrementing integer (currently in the 40s). This is NOT the same as the marketing version ("v1.0"). The mapping is: v0 = revisions 1–39 (internal testing), v1.0 = revision 40+ (public launch). Each API response that includes `basketVersion` reflects the on-chain revision number, not the marketing version.

## 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 |
| Contract | `0xE4FC0d3c388D766362992d6985556CF8907276A6` |
| Deployed | June 17, 2025 (basket v0) |
| Public launch | April 7, 2026 (basket v1.0) |

Read functions on the contract:

| Function | Returns |
|---|---|
| `lastRevisionVersion()` | Current basket version number |
| `getLatestRevision()` | Full latest version (model keys, prices, tier weights, workload, SCU, content hash) |
| `getRevision(uint256 version)` | Full version by number |
| `getModelPrices(string modelKey)` | Input price, output price, tier, and exists flag for latest version |
| `getModelPrices(string modelKey, uint256 version)` | Input price, output price, tier, and exists flag at a specific version |
| `getRevisionScuWei(uint256 version)` | SCU (wei, 18 decimals) for a specific version |

Basescan read-contract UI: https://basescan.org/address/0xE4FC0d3c388D766362992d6985556CF8907276A6#readContract

Prices are returned in wei (18 decimals). Divide by 10^18 for USD amounts.

## 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 | Purpose |
|---|---|---|
| GET | `/v1/oracle/scu` | Current SCU, tier breakdown, basket version |
| GET | `/v1/oracle/models` | All basket models with tier, provider, per-million pricing |
| GET | `/v1/oracle/model/:key` | Single model by pricing key |
| GET | `/v1/oracle/tiers` | Tier definitions, weights, current model assignments |
| GET | `/v1/oracle/basket` | Full basket composition |
| GET | `/v1/oracle/history?range=30d` | Hourly SCU history (30d / 90d / 1y / all) |
| GET | `/v1/oracle/reconstitutions` | Basket change history |
| GET | `/v1/oracle/health` | Latest version number and confirmation timestamp |

**`/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: current SCU breakdown, SCU value in USD, routing fee rate, basket version, and last-updated timestamp.

### Current SCU — response shape

The `breakdown` object is already tier-weighted (each value is `capped_mean × weight`); summing the three entries yields `scuUsd`. Example values are illustrative; fetch the live endpoint for current numbers.

```json
{
  "scuUsd": 0.006494986,
  "breakdown": {
    "frontier": 0.003449676375,
    "standard": 0.00250519,
    "lightweight": 0.000540119625
  },
  "referenceWorkload": { "inputTokens": 1000, "outputTokens": 500 },
  "methodology": "Capped equal-weight across 3 tiers (frontier 30%, standard 40%, lightweight 30%)",
  "updatedAt": "2026-04-21T13:54:38.820Z"
}
```

### Full basket — response shape

Top-level `models` array; each entry carries identity, tier, integration status, and both raw and marked-up per-million pricing in $COMPUTE and USD. Example values are illustrative.

```json
{
  "models": [
    {
      "id": "gpt-5.4",
      "displayName": "GPT-5.4",
      "provider": { "key": "openai", "name": "OpenAI" },
      "tier": "frontier",
      "integrated": true,
      "ctPricePerMillion": { "input": 378, "output": 2269 },
      "usdPricePerMillion": { "input": 2.49858, "output": 14.99809 },
      "markedUpCtPricePerMillion": { "input": 396.9, "output": 2382.45 },
      "markedUpUsdPricePerMillion": { "input": 2.623509, "output": 15.747995 },
      "oracleKeyPrefix": "gpt-5.4"
    }
  ]
}
```

**Field: `integrated`** — `true` if the model is available for inference routing through Compute Finance; `false` if the model is in the CPI basket for pricing reference only.

### Health — response shape

```json
{
  "latestRevisionVersion": 23,
  "latestRevisionConfirmedAt": "2026-04-21T13:54:38.820Z",
  "lastSyncAt": "2026-05-07T10:15:30.000Z",
  "stale": false
}
```

### Basket — response shape

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

```json
{
  "models": [
    {
      "id": "gpt-4.1",
      "displayName": "GPT-4.1",
      "provider": { "key": "openai", "name": "OpenAI" },
      "tier": "frontier",
      "integrated": true,
      "ctPricePerMillion": { "input": 133.3, "output": 533.3 },
      "usdPricePerMillion": { "input": 2.0, "output": 8.0 },
      "markedUpCtPricePerMillion": { "input": 139.97, "output": 559.97 },
      "markedUpUsdPricePerMillion": { "input": 2.1, "output": 8.4 },
      "oracleKeyPrefix": "gpt-4.1",
      "releasedAt": "2025-04-14T00:00:00Z"
    }
  ],
  "scu": { "frontier": 2.35, "standard": 1.12, "lightweight": 0.57, "total": 4.04 },
  "scuUsd": 4.04,
  "routingFeeRate": 0.05,
  "revisionVersion": 42,
  "basketVersion": 42,
  "lastUpdated": "2026-05-07T10:15:30Z"
}
```

### Tiers — response shape

`GET /v1/oracle/tiers` — tier breakdown with weights and per-tier SCU contribution.

```json
{
  "tiers": {
    "frontier": { "weight": 0.3, "models": 4, "avgCostUsd": 7.82, "contribution": 2.35 },
    "standard": { "weight": 0.4, "models": 5, "avgCostUsd": 2.81, "contribution": 1.12 },
    "lightweight": { "weight": 0.3, "models": 3, "avgCostUsd": 1.89, "contribution": 0.57 }
  },
  "scuUsd": 4.04
}
```

### History — response shape

`GET /v1/oracle/history?range=30d` — daily SCU time series with per-tier breakdown.

```json
{
  "range": "30d",
  "from": "2026-04-07",
  "to": "2026-05-07",
  "count": 31,
  "data": [
    { "date": "2026-04-07", "scu": 3.89, "frontier": 2.15, "standard": 1.02, "lightweight": 0.72, "basketVersion": 40 },
    { "date": "2026-05-07", "scu": 4.04, "frontier": 2.35, "standard": 1.12, "lightweight": 0.57, "basketVersion": 42 }
  ]
}
```

### Reconstitutions — response shape

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

```json
{
  "entries": [
    {
      "id": "recon-1",
      "revisionVersion": 42,
      "previousVersion": 41,
      "publishedAt": "2026-04-16T14:30:00Z",
      "summary": "Quarterly reconstitution: replaced claude-opus-4.6 with claude-opus-4.7",
      "scuBefore": 3.89,
      "scuAfter": 4.04,
      "changes": [
        { "type": "ModelRemoved", "modelKey": "claude-opus-4.6", "tier": "frontier", "description": "Removed claude-opus-4.6 from frontier tier" },
        { "type": "ModelAdded", "modelKey": "claude-opus-4.7", "tier": "frontier", "description": "Added claude-opus-4.7 to frontier tier" }
      ],
      "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 hourly, 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.

## What V1 is NOT

The oracle is a public reference price, not a tradeable asset or payment rail.

- **Not a token.** There is no ERC-20 and no plans for one in V1. Points earned on compute.finance have no monetary value.
- **Not a marketplace.** Compute Finance does not match buyers and sellers of inference. The CPI is a reference price, not a quote you can execute against.
- **Not an inference proxy.** Compute Finance does not resell, route, or intermediate provider API calls. All inference pricing comes from official provider rate cards.
- **Not a first-party typed SDK.** V1 does not ship a first-party typed SDK. Use the OpenAPI spec to generate clients with `openapi-generator`, `openapi-typescript`, or `oapi-codegen`. AI agents that consume tools rather than HTTP can use the official Compute Finance MCP — see "Compute Finance MCP" below.

**Pricing fields explained.** `usdPricePerMillion` is the raw provider rate card price. `markedUpUsdPricePerMillion` applies the routing fee markup (currently 5%) that would be charged if the model were accessed through a future inference proxy. `ctPricePerMillion` and `markedUpCtPricePerMillion` express the same values denominated in $COMPUTE tokens at the current peg. In V1, only the raw `usdPricePerMillion` reflects actual provider pricing — the marked-up and CT-denominated fields are informational.

## Compute Finance MCP

Compute Finance ships an official MCP package for AI agent tool use. Repository: https://github.com/compute-finance/compute-finance-mcp. Also published on npm. It exposes ten Model Context Protocol tools across oracle data (SCU, basket, models, tiers, history, reconstitutions, health), session-cost math, and local history — the canonical way for AI agents to query Compute Finance.

## 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"
- "On-chain at https://basescan.org/address/0xE4FC0d3c388D766362992d6985556CF8907276A6"

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.

- https://api.compute.finance/v1/oracle/scu
- https://api.compute.finance/v1/oracle/models
- https://api.compute.finance/v1/oracle/model/:key
- https://api.compute.finance/v1/oracle/tiers
- https://api.compute.finance/v1/oracle/basket
- https://api.compute.finance/v1/oracle/history?range=30d
- https://api.compute.finance/v1/oracle/reconstitutions
- https://api.compute.finance/v1/oracle/health