Request a feed

Map the dataset

Pick a catalog leaf and choose one frequency, one data_col, and the facet filters that isolate the series you want. The catalog already lists each dataset’s available frequencies, columns, and facet ids, so the mapping is a selection, not a guess. That selection becomes one EiaFeed row.

Fetch with the generic adapter

One adapter (agent/src/eia.ts, fetchLatest) serves every EIA dataset, because EIA APIv2 is one uniform faceted API. It builds the request from the mapping, takes the single latest row, scales the value to an integer at the feed’s decimals with exact decimal-string math (no float drift), and computes the deterministic source_hash.

GET https://api.eia.gov/v2/petroleum/pri/spt/data
  ?api_key=...&frequency=daily&data[0]=value
  &facets[series][]=RWTC
  &sort[0][column]=period&sort[0][direction]=desc&offset=0&length=1

The source_hash commits to the route, frequency, sorted facets, period, value, and unit, so the same reading hashes identically wherever it is produced. See provenance.

Register the metadata (eligibility-gated)

The agent calls FeedRegistry.register_feed with the self-describing metadata. Registering a new feed requires a ZK eligibility credential and records the caller as the feed’s claimant; only the claimant can update or attest it afterwards. The scripts derive title and description from the mapping and set source to EIA, so a feed only needs the row above. Re-registering the same feed_id updates it in place and never double-counts.

// agent/src/tools.ts: claimant entry point (ZK-eligible callers only)
await registerFeed(
  asset_id, decimals, unit, title, /* source */ 'EIA', route, frequency, description,
); // -> FeedRegistry.register_feed (gas limit 8 CSPR)

Attest the value (attester-gated)

The agent reads the latest value back through the adapter and calls AttestationRegistry.attest with the exact period, amount (the scaled integer), and source_hash.

const r = await readEiaFeed(asset_id);            // adapter: latest row, scaled + hashed
await attest(r.asset_id, r.period, r.amount, r.source_hash); // gas limit 20 CSPR

Find the dataset

Search the catalog by keyword or family (route prefix) to confirm the route, the frequencies, the columns, and the facet ids you can filter on:

curl 'http://localhost:4030/v1/datasets?q=diesel&family=petroleum'
# { "total": ..., "datasets": [
#   { "route": "petroleum/pri/gnd", "name": "...", "frequencies": ["weekly"],
#     "columns": ["value"], "facets": ["series", "duoarea", "product"] }, ... ] }

Open a request

Specify the mapping fields below. The operator adds one EiaFeed row and runs the populate script, and the feed goes live on-chain.