Feeds & feed_id

A feed is a single real-world data series that Claros tracks and attests on Casper: WTI crude spot price, Lower-48 electricity demand, San Diego parking revenue, and so on. Every feed carries two things on-chain, a self-describing metadata record (what it is, its unit, how many decimals) and a latest attested value.

A feed_id is the stable, unique string that names that series. It is the only identifier you ever need. Pass it to the SDK, the REST API, or a cross-contract call and the reading comes back. If you have used Pyth, a feed_id plays the same role as a Pyth price feed id.

Anatomy of a feed

A feed is split across two contracts so that a value never travels without the context needed to interpret it. This is the Pyth model: a price ships with its exponent. Both records are keyed by the same feed_id.

Metadata lives in the FeedRegistry. get_feed(feed_id) -> Option<Feed>:

Value lives in the AttestationRegistry. get_latest(feed_id) -> Option<Attestation>:

Put the two together and you have a reading. For EIA.PET.PRICE.WTI.DAILY the value is 78940000 / 10^6 = $78.94 / bbl.

The SDK and REST API return both halves pre-joined and scaled as one reading object:

The feed_id naming convention

To both the contracts and the SDK a feed_id is an opaque string key. Nothing parses it. The naming scheme below is a human convention that makes ids readable and predictable; the machine mapping from a feed_id to its upstream query is a lookup table, not derived from the string.

EIA energy feeds

Energy feeds from the U.S. Energy Information Administration follow a dotted, uppercase scheme:

EIA.<FAMILY>.<METRIC>[.<SUBMETRIC>].<SPECIFIER>.<FREQ>

The first segment is always EIA, and the last segment is always the frequency. Everything in between identifies the quantity. Taking EIA.PET.PRICE.WTI.DAILY:

Some ids carry an extra segment when a family has sub-metrics, for example EIA.ELEC.RETAIL.PRICE.US_ALL.MONTHLY (family ELEC, metric path RETAIL.PRICE, specifier US_ALL).

The <FREQ> suffix is one of DAILY, WEEKLY, MONTHLY, QUARTERLY, ANNUAL, or HOURLY. The <FAMILY> token maps to an EIA route family:

A few real feed ids live on-chain today:

Civic feeds

Non-EIA sources use short, provider-specific ids rather than the dotted scheme. The flagship civic feed is OP-1, San Diego parking revenue (source "City of San Diego"), which returns for example $2,734.20 for period 20260623. A feed_id can be any string the registrar chooses; the EIA convention is simply the scheme Claros uses for EIA series.

One feed_id, both registries

The same feed_id is the dictionary key in both contracts: FeedRegistry.feeds (metadata) and AttestationRegistry.latest (value). Read one for context, the other for the number, and divide.

import { ClarosOracle } from 'claros-oracle';
 
const claros = new ClarosOracle(); // Casper testnet defaults baked in
 
// one call: metadata + value + human number
const r = await claros.getReading('EIA.PET.PRICE.WTI.DAILY');
// r.value      === 78.94
// r.amount     === 78940000n
// r.decimals   === 6
// r.unit       === '$/bbl'
// r.updated_at === 1750636800000  (epoch ms)
 
// or the two halves separately, same id into each registry
const meta  = await claros.getFeed('EIA.PET.PRICE.WTI.DAILY');  // FeedRegistry
const value = await claros.getValue('EIA.PET.PRICE.WTI.DAILY'); // AttestationRegistry

# one feed, fully joined and scaled, read live from on-chain state
curl https://<claros-api>/v1/feeds/EIA.PET.PRICE.WTI.DAILY

{
  "feed_id": "EIA.PET.PRICE.WTI.DAILY",
  "value": 78.94,
  "amount": "78940000",
  "decimals": 6,
  "unit": "$/bbl",
  "title": "WTI crude spot",
  "source": "EIA",
  "route": "petroleum/pri/spt",
  "frequency": "daily",
  "period": 20260622,
  "source_hash": "…",
  "updated_at": 1750636800000
}

// from your own Odra contract, the same feed_id keys both registries
let value = AttestationRegistryRef::new(env, attestation_registry)
    .get_latest(feed_id.clone());          // Option<Attestation>
let meta  = FeedRegistryRef::new(env, feed_registry)
    .get_feed(feed_id);                     // Option<Feed>
 
// real value = value.amount / 10^meta.decimals

Enumerating feeds

The set of feeds is discoverable on-chain, no indexer required. The FeedRegistry maintains an index so the whole catalog can be walked.

import { ClarosOracle } from 'claros-oracle';
 
const claros = new ClarosOracle();
 
const ids = await claros.listFeedIds(); // ['EIA.PET.PRICE.WTI.DAILY', 'OP-1', …]
const n   = await claros.feedCount();   // 37
const id0 = await claros.feedIdAt(0);   // first registered feed_id

# every feed live on-chain, each with metadata + latest value
curl https://<claros-api>/v1/feeds
# { "count": 37, "feeds": [ { "feed_id": "EIA.PET.PRICE.WTI.DAILY", "value": 78.94, … }, … ] }

let n  = FeedRegistryRef::new(env, feed_registry).feed_count();     // u64
let id = FeedRegistryRef::new(env, feed_registry).get_feed_at(0);  // Option<String>

The SDK’s listFeedIds() is just the loop below, which is also exactly what the REST API does to build GET /v1/feeds:

Today 39 feeds are registered: the EIA energy mappings in agent/src/eia-feeds.ts, the civic feed OP-1, and the operator-claimed solar feed EIA.ELEC.GEN_SUN.US48.HOURLY. 38 serve live values; electricity interchange is registered but intentionally unattested (it is a signed metric).

From feed_id to upstream data

Each EIA feed_id resolves to one concrete EIA API v2 query, a tuple of { route, frequency, data_col, facets }. For example EIA.PET.PRICE.WTI.DAILY resolves to:

{
  route: 'petroleum/pri/spt',
  frequency: 'daily',
  data_col: 'value',
  facets: { series: 'RWTC' }, // unit $/bbl, decimals 6
}

The facets object holds the filters that pin a single series within a dataset (here series: 'RWTC' selects the Cushing WTI spot price). To browse the whole EIA universe (232 datasets) and the routes, columns, and facets you can filter on, use discovery:

curl "https://<claros-api>/v1/datasets?family=petroleum&q=price"

See the EIA data model for a full treatment of routes, frequencies, columns, and facets.

Next