API Reference

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.

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 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). Present the key in either header form:

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 problem;
• a valid key that lacks the plane’s scope is a 403 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 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

{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:

{
  "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

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 volume/open-interest metrics in USD (venues that report contract counts, such as Kalshi, are dollarized as contracts × current price — flagged with a basis field, native counts attached under native);
• 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

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

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, never this resource.

Latest committed round

curl https://api.mecone.trade/api/v1/indices/MCPI/rounds/latest

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

{
  "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

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

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.

Benchmarks

The index reference values the terminal renders — one catalog request is the whole board.

curl https://api.mecone.trade/api/v1/benchmarks
curl "https://api.mecone.trade/api/v1/benchmarks?category=Energy"
curl https://api.mecone.trade/api/v1/benchmarks/MWTI/snapshots/latest
curl "https://api.mecone.trade/api/v1/benchmarks/MWTI/history?range=1w&resolution=1h"

history takes an optional range (1d, 1w, 1m, 6m, 1y, all) and resolution (auto — the default — 1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d, 1w); an unsupported combination is a 400 unsupported-history-resolution problem. Without a range, the route serves the frozen no-query v1 tick series unchanged.

Every row carries a family (commodities today) and a category. Other benchmark kinds join this same collection under their own family rather than under new paths, so narrowing the catalog is always a filter and never a different route — reclassifying a benchmark never breaks a link. meta.families lists what a deployment publishes; a family it does not carry returns an empty collection rather than a 404.

Path change. These resources were first published under /api/v1/commodities. That path still works and returns byte-identical bodies, but carries RFC 9745 Deprecation: true and a Link: …; rel="successor-version" pointing at /api/v1/benchmarks. Payload links always resolve to the canonical path, so a client that follows self migrates itself.

Mecone Data Lake

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, 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:

{
  "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.

Standards and conventions

• OpenAPI Specification
• RFC 9457: Problem Details for HTTP APIs
• RFC 9111: HTTP Caching
• RFC 3339: Internet timestamps
• RFC 9745: Deprecation header
• NIST SP 800-228: API protection
• OWASP API Security Top 10