> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mecone.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# API Guide

> The versioned public API: resources, envelopes, keys, and conventions

Base URL: `https://api.mecone.trade` · JSON over HTTPS

The versioned public API is the recommended integration surface. Version `v1`
uses resource-oriented paths, a stable response envelope, wire-stable decimal
string companions,
RFC 9457 errors, request IDs, ETags, and a generated OpenAPI contract.

```bash theme={null}
curl https://api.mecone.trade/api/v1/info
```

Anonymous testnet reads stay open on every read endpoint documented on this
page — no key is required today, and unauthenticated access carries no
commercial SLA. The per-consumer credential layer is live: licensed and
attributable integrations receive scoped API keys, described under
[API keys](#api-keys) below.

Three internal surfaces still take a static bearer token: the operator
`POST /api/refresh`, the private research preview under `/api/research/indices`,
and the internal `/metrics` scrape. In addition, scoped `mck_` API keys are
accepted on every public read plane, and credential administration itself lives
on an operator-only plane under `/api/admin/**` — neither changes the anonymous
read behavior above.

## API keys

Anonymous testnet reads need no key. Licensed integrations receive a scoped,
per-consumer API key — an opaque `mck_…` credential. Terminal users mint and
manage their own keys from the terminal's API Keys page; venue keys are issued
during onboarding (write to [info@mecone.trade](mailto:info@mecone.trade)).
Present the key in either header form:

```bash theme={null}
curl -H "X-API-Key: mck_…" https://api.mecone.trade/api/v1/indices
curl -H "Authorization: Bearer mck_…" https://api.mecone.trade/api/v1/indices
```

Each key carries a least-privilege scope set drawn from `indices:read`,
`benchmarks:read`, `lake:read`, `markets:read`, and `research:read` — one scope
per read plane — plus a per-key per-minute rate limit and an optional expiry.
Keys can be revoked or rotated at any time.

A key may additionally carry a **per-index entitlement list** — the
mechanism behind scoped trials. One list spans the whole catalog, by slug
(say `us-gdp`, `us-cpi-yoy`, `gpu-h100-rental`). An entitled key reads only
the slugs fixed at issuance, on both planes; a key with no list reads
everything. The list can be widened or cleared at any time — contact us and
the change is live within a minute.

A presented key is strictly enforced and never falls back to anonymous access:

* an unknown, revoked, or expired key is a `401`
  [`credential-invalid`](/problems#credential-invalid) problem;
* a valid key that lacks the plane's scope is a `403`
  [`credential-scope`](/problems#credential-scope) problem;
* an entitled key reading a benchmark or flagship index outside its list is a
  `403` `benchmark-not-entitled` problem;
* a key over its per-minute limit is a `429`
  [`rate-limited`](/problems#rate-limited) problem carrying `Retry-After`,
  `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers.

Requests that present no key are unaffected: they remain open anonymous
testnet reads.

## Resources

| Path                                            | Meaning                                                                                                               |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `GET /api/v1/info`                              | API discovery, versioning, and data semantics                                                                         |
| `GET /api/v1/indices`                           | Compact catalog of public indices                                                                                     |
| `GET /api/v1/indices/{id}`                      | Stable index metadata, methodology, contracts, weights, and release details                                           |
| `GET /api/v1/indices/{id}/snapshots/latest`     | Latest live/indicative calculation                                                                                    |
| `GET /api/v1/indices/{id}/history`              | Stored tick series as OHLC buckets; `range` + `resolution`                                                            |
| `GET /api/v1/indices/{id}/rounds/latest`        | Latest canonical API-committed round; fails closed if absent                                                          |
| `GET /api/v1/indices/{id}/distributions/latest` | Latest source probability distribution and its own observation clock                                                  |
| `GET /api/v1/indices/{id}/statistics/latest`    | Trailing derived statistics: gated 30-print daily/annualized volatility and a 12-month level range                    |
| `GET /api/v1/indices/{id}/daily-closes`         | Six New York daily reference closes, with per-row provenance disclosure                                               |
| `GET /api/v1/indices/{id}/news`                 | Newest-first news and context items about the index from licence-labelled sources; filter by `kind`, `since`, `limit` |
| `GET /api/v1/lake`                              | Data-lake discovery: venues served, exclusions, and tape semantics                                                    |
| `GET /api/v1/lake/venues`                       | Per venue: tape origin, populated price fields, book availability, cadence, coverage                                  |
| `GET /api/v1/lake/venues/{venue}`               | One venue's semantics and its collected days                                                                          |
| `GET /api/v1/lake/venues/{venue}/snapshots`     | Snapshot times collected for one venue-day                                                                            |
| `GET /api/v1/lake/venues/{venue}/quotes`        | Normalized quote rows for one snapshot, paginated                                                                     |
| `GET /api/v1/openapi.json`                      | Curated OpenAPI 3.1 contract for the routes above                                                                     |

`{id}` accepts the stable Mecone symbol (`MCPI`) or slug (`us-cpi-yoy`).
Responses return the canonical symbol and slug; generated links use the slug.

## Response envelope

Successful responses have three top-level members:

```json theme={null}
{
  "data": { "type": "index", "id": "MCPI" },
  "meta": {
    "api_version": "v1",
    "schema_version": "mecone-public-api-v1"
  },
  "links": { "self": "/api/v1/indices/us-cpi-yoy" }
}
```

Additive fields may be introduced within `v1`. A removal, type change, or
semantic change normally requires a new major URI version. The versioned API is
still pre-GA; this release removes inadvertently exposed transformation
implementation fields before partner migration. The legacy partner endpoints
are not redirected or reinterpreted and retain their existing display fields.

## Index metadata

```bash theme={null}
curl https://api.mecone.trade/api/v1/indices/MCPI
```

The index resource contains:

* identity and the curated `thesis` description;
* methodology version, estimand, high-level calculation class, transformation disclosure status,
  and venue weights. The `methodology.index_transformation` block describes the calculation
  class without exposing implementation parameters; lifecycle and release
  records remain available in their specifically labeled resources;
* prediction-market contracts, roles, lifecycle clocks, links, and source-native
  volume/open-interest units;
* latest and next release or resolution details; and
* links to the latest snapshot, committed round, and distribution.

Distribution data is a separate resource so clients do not mistake a current
source distribution for evidence recorded with an older committed round.

## Live snapshot

```bash theme={null}
curl https://api.mecone.trade/api/v1/indices/MCPI/snapshots/latest
```

A snapshot is explicitly `scope: "live_indicative"` and `official: false`.
It includes separate `source_observed_at` and `computed_at` clocks plus the
current publication/oracle eligibility state. It is appropriate for charts and
marks when a venue's rules designate this transport; it is not automatically a
settlement record.

## Stored history

```bash theme={null}
curl "https://api.mecone.trade/api/v1/indices/MANTH/history?range=1m&resolution=auto"
```

The immutable tick series behind the terminal charts, served as OHLC buckets
over the requested window. `range` is `1d`, `1w`, `1m`, `6m`, `1y` or `all`
(default `1m`); `resolution` is `auto` or an explicit bucket (`1m`…`1w`); a
combination too fine for the range is a `400` `unsupported-history-resolution`
problem. Every response discloses its own coverage: `meta.availability`
(`available` | `partial` | `empty`) and `meta.coverage` state exactly which
slice of the requested window the store holds, so a client never mistakes a
short series for a quiet market.

History starts at each feed's launch — the indices are derived from live
prediction markets, so there is no pre-launch backfill. The series is
indicative chart history (`official: false`, `settlement_grade: false`):
settlement-grade history is the signed official rounds on the
[oracle](/oracle/signed-rounds), never this resource.

## Latest committed round

```bash theme={null}
curl https://api.mecone.trade/api/v1/indices/MCPI/rounds/latest
```

This endpoint returns only the latest canonical API-committed scalar tuple:

```json theme={null}
{
  "data": {
    "type": "index_round",
    "status": "api_committed",
    "official": true,
    "round_id": "2026-07-16T04:00:00+00:00",
    "value": {
      "decimal": "3.4972978473895",
      "number": 3.4972978473895,
      "unit": "%",
      "display": null
    },
    "chain_confirmation": {
      "status": "not_asserted"
    }
  }
}
```

Use `value.decimal` when a client needs a wire-stable string representation;
`value.number` is a binary-floating-point convenience for charts. Both originate
from the same already-computed Python scalar, so this is not yet a source-signed
integer-and-scale representation. The clocks remain distinct.
`api_committed` does **not** claim that the same tuple was confirmed on-chain.
It also does not mean the round is fresh: consumers must enforce the maximum age
defined by their own market rules against `clocks.computed_at`.
`clocks.round_effective_at` is the five-minute round bucket (and matches
`round_id`); it is deliberately not labeled as a database commit time because
the legacy store does not record that clock for every feed.
For the current Arbitrum Sepolia pilot, the venue's rules must name either this
API transport or the on-chain transport and must not mix independent `latest`
reads. When no committed round exists, this route returns `503`; it never
launders a live fallback into an official-looking response.

## Probability distribution

```bash theme={null}
curl https://api.mecone.trade/api/v1/indices/MCPI/distributions/latest
```

Each outcome includes its label, numerical support, normalized probability,
percentage, and modal flag. The resource also identifies its observation basis,
normalization state, relationship to the displayed index, and `observed_at`
clock. This is the data used for website distribution visualizations.

## Index news

```bash theme={null}
curl "https://api.mecone.trade/api/v1/indices/MCPI/news?limit=20&kind=official_release,venue_context"
```

Newest-first, dated items *about* an index, from sources whose terms let us re-serve them.
Every item carries:

* `kind` — `official_release` (the anchor agency's own print, e.g. the BLS CPI release),
  `official_statement` (FOMC statements and minutes), `filing` (SEC EDGAR Form D / S-1 / F-1 by
  the pre-IPO entity — `relevance: direct` — or a fund/SPV vehicle named after it — `related`;
  links go to the human-readable EDGAR filing index), `venue_context` (the source venue's own
  context on the bound contract: **Polymarket's market-context narrative, which is AI-generated
  by the venue and not verified by Mecone** — such items say so in their title, `source.name`,
  `provenance.note` and `payload.generated_by: "venue_ai"`, and should be displayed as the
  venue's commentary, never as fact; or Kalshi's contract terms — strike ladder, settlement
  sources, expected settlement and close — versioned so a change is a new item), `venue_event`
  (something the venue did or scheduled: a Kalshi
  settlement with the winning strike, or a Kalshi milestone such as "BLS CPI data release for
  August 2026" with its start/end window), `editorial` (a publisher post that links the bound
  contract — headline and link only);

* `relevance` — `direct` (about the index's own release or contract) or `related` (surrounding
  context such as monetary-policy statements attached to the macro indices);

* `licence` — `public_domain` (US-government publication), `venue_public_api` (read from the
  venue's public API; display with venue attribution, subject to its terms) or
  `headline_link_only` (the publisher's text is never served);

* `source{id,name,domain}`, `url`, `t` (the item's own clock), `observed_at` (first seen by the
  backend), an optional `summary` (≤ 2,000 characters; always `null` for `headline_link_only`),
  and `provenance{feed, retrieved_at}`.

* `authorship` — the editorial classification, made explicit so no client has to infer it:
  `primary_document` (an agency release, an SEC filing, a settled Kalshi market, a venue's
  contract terms or milestone — a document that exists independently of anyone's model),
  `venue_generated` (text a venue's own model wrote — Polymarket's market context; always
  carries `provenance.note`), `editorial` (a publisher headline, link only).

**Default policy.** Without filters the response contains **primary documents and editorial
headlines about the index's own contract only** (`authorship=primary_document,editorial`,
`relevance=direct`). Venue-generated commentary is served only with
`?authorship=venue_generated` (or `all`), and related items (e.g. SPV filings that reference a
company) only with `?relevance=related` (or `all`); `data.policy` states the defaults and what
was applied. If you display venue-generated items, show `provenance.note` with them and do not
interleave them with primary documents.

`data.sources` lists the feeds configured for the index; `data.availability` is `available`,
`empty` (sources configured, nothing yet), `no_sources` (none configured for this index) or
`disabled`. Query parameters: `limit` (1–100, default 50), `kind` (comma-separated subset of the
kinds above), `relevance` (`direct` | `related` | `all`), `authorship` (comma-separated subset or
`all`), `since` (RFC 3339). Items are metadata about a source document, never a substitute for
it, and are not settlement-relevant.

## Mecone Data Lake

```bash theme={null}
curl https://api.mecone.trade/api/v1/lake
curl https://api.mecone.trade/api/v1/lake/venues/limitless/snapshots?date=2026-08-17
curl "https://api.mecone.trade/api/v1/lake/venues/limitless/quotes?date=2026-08-17&at=0002"
```

A read-only projection of the multi-venue prediction-market tape Mecone collects, so a snapshot
can be inspected without an AWS credential. Collected dates and snapshot times slide forward as
the tape grows — take them from the venue resource (`dates`) and its `snapshots` listing rather
than copying the values above. `at` is the object key's `HHMM`, which is the **cycle
start**, not the response time. `quotes` paginates with `page` (default 1) and `page_size`
(default 100, maximum 500); a `page` past the end is a `404` `page-not-found` problem. Rows are
produced by the lake's own normalizer, so an API row and a lake row cannot disagree.

Four semantics are carried in the payload rather than only in prose, because each one is a
mistake that produces a plausible number instead of an error:

* **An unquoted side is `null`, never `0`.** Limitless, Myriad and ForecastEx publish no order
  book at all — one indicative price per outcome. `mid` and `spread` are emitted **only** when
  both sides were quoted on a venue with a two-sided book; for a bookless venue they are absent,
  not zero.
* **Populated price fields differ per venue.** Each venue publishes `quote_fields`, the columns
  it actually fills. Do not assume `bid` and `ask` exist.
* **`tape_origin` names any venue that mirrors another exchange's book.** A mirror is not a
  second opinion on a price, and averaging it against its source is averaging a book with itself.
* **A snapshot may be a partial board.** `completeness.status` is `incomplete` when the collector
  recorded a failure and `not_recorded` when the writing collector does not record completeness
  at all — absence of a failure is not a claim of completeness.

Venues are served from an **explicit allow-list**. Licence-gated and vendor-purchased data is not
served at any path, and a venue added to the lake later stays excluded until it is consciously
allowed; `GET /api/v1/lake` publishes each exclusion with its reason. Listing is cheap and
reading is not, so page sizes are capped and snapshots above a published byte ceiling are refused
with `413` rather than rendered — whole-day analysis belongs on the bulk path.

## HTTP behavior

* Responses include `X-Request-ID` and `X-API-Version`.
* Read resources include an `ETag`; send `If-None-Match` to receive `304 Not Modified`.
* Current resources use short, explicit cache lifetimes.
* Any resource that cannot be served safely fails closed with a `503` problem
  document (e.g. [`official-round-unavailable`](/problems#official-round-unavailable),
  [`index-unavailable`](/problems#index-unavailable)) carrying `Retry-After` —
  never a stale or fabricated payload.
* Errors use `application/problem+json` with `type`, `title`, `status`,
  `detail`, `instance`, and `request_id`.
* Temporary failures may include `Retry-After`.
* Timestamps are RFC 3339 strings with explicit UTC offsets.

Example error:

```json theme={null}
{
  "type": "https://docs.mecone.trade/problems#index-not-found",
  "title": "Index not found",
  "status": 404,
  "detail": "The requested public index does not exist.",
  "instance": "/api/v1/indices/not-a-feed",
  "request_id": "5e5a51b8c8c24dbf93e403bdc36ed84b"
}
```

## Legacy compatibility

The unversioned `/api/markets` routes remain operational and unchanged for the
website, oracle publisher, data lake, existing scripts, and partner pilots.
They are not redirected to `v1`. New integrations should use the versioned API;
legacy deprecation will only begin after partner coordination and usage
telemetry, with standard `Deprecation` and `Sunset` headers.

A WebSocket at `wss://api.mecone.trade/ws` sends a full market snapshot on
connect, then streams live index updates; it is the terminal's transport and
carries the legacy payload shapes.

The legacy operator `POST /api/refresh` is the deliberate security exception:
it now requires a dedicated bearer token and fails closed when that token is not
configured. It is not a public integration endpoint.

<Note>
  `/api/v1/indices/{id}/rounds/latest` is the canonical API-committed record.
  The latest value confirmed on-chain is a separate transport today. See
  [Consuming the Feeds](/oracle) before writing settlement rules.
</Note>

## Standards and conventions

* [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
* [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html)
* [RFC 9111: HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html)
* [RFC 3339: Internet timestamps](https://www.rfc-editor.org/rfc/rfc3339.html)
* [RFC 9745: Deprecation header](https://www.rfc-editor.org/rfc/rfc9745.html)
* [NIST SP 800-228: API protection](https://doi.org/10.6028/NIST.SP.800-228)
* [OWASP API Security Top 10](https://owasp.org/API-Security/)