REST API

The Claros REST API is the Hermes of Claros: a small HTTP service (services/claros-api, an Express app on port 4030) that serves real-world-data feeds read directly from Casper on-chain state, plus the full EIA dataset discovery catalog. It is the API way to read Claros, modelled on Pyth’s price service: any language, no key, free.

The service holds no database and runs no indexer. Each request reads Casper global state through the TypeScript SDK (claros-oracle), so a response always reflects the latest value attested on-chain at request time.

Endpoints

Authentication and CORS

There is none, by design. Reads are free.

• No API key. No Authorization header, no token, no signup.
• Open CORS. The service sends Access-Control-Allow-Origin: *, so you can call it directly from a browser or frontend with fetch, no proxy required.
• JSON only. Every response is application/json.

GET /v1/feeds/:id

Return the full reading for one feed: its self-describing metadata, its latest on-chain value, and the scaled human number, in a single object. This is the endpoint you call to read a value.

GET /v1/feeds/EIA.PET.PRICE.WTI.DAILY HTTP/1.1
Host: localhost:4030

curl http://localhost:4030/v1/feeds/EIA.PET.PRICE.WTI.DAILY

Path parameters

This endpoint takes no query parameters.

Response fields

The body is a single Reading object. Fields appear in this order.

Example response

200 OK for GET /v1/feeds/EIA.PET.PRICE.WTI.DAILY:

{
  "feed_id": "EIA.PET.PRICE.WTI.DAILY",
  "decimals": 6,
  "unit": "$/bbl",
  "title": "Cushing, OK WTI Spot Price FOB",
  "source": "EIA APIv2",
  "route": "petroleum/pri/spt",
  "frequency": "daily",
  "description": "Cushing, OK crude oil (WTI) spot price, free on board, US dollars per barrel.",
  "value": 78.94,
  "amount": "78940000",
  "period": 20260622,
  "source_hash": "9f2c1ad4b7e0…",
  "updated_at": 1781740800000
}

Reading it: amount = 78940000, decimals = 6, so value = 78940000 / 10^6 = 78.94 in $/bbl. The period 20260622 is the trading day, and updated_at is when the agent attested it.

Errors

// 404 Not Found
{ "error": "feed not found on-chain: EIA.FOO.BAR" }

GET /v1/feeds

List every feed that is live on-chain, each as a full reading (metadata plus latest value). There are 38 feeds live today. There are no parameters and no pagination: the call enumerates all feed ids, then reads each one, so it is the heaviest endpoint. To read a single value, prefer GET /v1/feeds/:id.

curl http://localhost:4030/v1/feeds

Response fields

Example response

{
  "count": 37,
  "feeds": [
    {
      "feed_id": "EIA.PET.PRICE.WTI.DAILY",
      "value": 78.94,
      "unit": "$/bbl",
      "decimals": 6,
      "amount": "78940000",
      "period": 20260622,
      "updated_at": 1781740800000
    },
    {
      "feed_id": "EIA.NG.PRICE.HENRYHUB.DAILY",
      "value": 3.16,
      "unit": "$/MMBtu",
      "decimals": 6,
      "amount": "3160000",
      "period": 20260622,
      "updated_at": 1781740800000
    }
  ]
}

Each entry is abbreviated above; the live response carries every field listed in the reading fields table. On an upstream RPC failure this endpoint returns 502 with { "error": "<message>" }.

GET /v1/datasets

Discover the universe of EIA datasets Claros can attest. The EIA APIv2 is one uniform faceted API: every dataset has a route, a set of frequencies, a set of columns, and a set of facets (the filters). A Claros feed is exactly the tuple { route, frequency, data_col, facets }. This endpoint searches the full catalog of 232 datasets so you can find the route and facets behind a feed, or scout a new series to register.

curl "http://localhost:4030/v1/datasets?family=electricity&q=price"

Query parameters

Both parameters are optional and combine: family is applied first, then q filters what remains. With neither, the endpoint returns the entire catalog. The top-level families are aeo, co2-emissions, coal, crude-oil-imports, densified-biomass, electricity, ieo, international, natural-gas, nuclear-outages, petroleum, seds, steo, and total-energy.

Response fields

Example response

200 OK for GET /v1/datasets?family=electricity&q=price:

{
  "total": 1,
  "datasets": [
    {
      "route": "electricity/retail-sales",
      "name": "Electricity Sales to Ultimate Customers",
      "frequencies": ["monthly", "quarterly", "annual"],
      "columns": ["revenue", "sales", "price", "customers"],
      "facets": ["stateid", "sectorid"]
    }
  ]
}

That one dataset already backs several live feeds, including EIA.ELEC.RETAIL.PRICE.US_ALL.MONTHLY and EIA.ELEC.RETAIL.SALES.US_ALL.MONTHLY: same route, one column and one set of facet values each. See live feeds for the mapped ones and the data catalog for the rest.

GET /health

A liveness probe. Returns 200 with the service name and the number of discovery datasets loaded.

curl http://localhost:4030/health

{ "status": "ok", "service": "claros-api", "datasets": 232 }

REST, the SDK, or a cross-contract call

The REST API, the SDK, and a cross-contract call all return the same on-chain reading. Pick by where your code runs.

curl http://localhost:4030/v1/feeds/EIA.PET.PRICE.WTI.DAILY

import { ClarosOracle } from 'claros-oracle'
 
const oracle = new ClarosOracle() // Casper testnet defaults baked in
const wti = await oracle.getReading('EIA.PET.PRICE.WTI.DAILY')
 
console.log(wti.value, wti.unit) // 78.94 $/bbl

#[odra::external_contract]
pub trait ClarosValues {
    fn get_latest(&self, asset_id: String) -> Option<Attestation>;
}
 
let att = ClarosValuesContractRef::new(self.env(), registry)
    .get_latest("EIA.PET.PRICE.WTI.DAILY".to_string())
    .unwrap_or_revert(&self.env());
// real price = att.amount / 10^6

Run the API yourself

The service is part of the Claros repo at services/claros-api. It is a small Express app with three dependencies (express, cors, and claros-oracle).

npm install

# services/claros-api/.env
PORT=4030
CASPER_NODE_RPC=https://node.testnet.casper.network/rpc
FEED_REGISTRY_PACKAGE_HASH=741cc223c14c2c00c9f06d7bb5c4be2f824fbf0c8b09a147bf1835570bddf5b6
ATTESTATION_REGISTRY_PACKAGE_HASH=236b510436c60b6a797d175c72c6014de367d43f1de1ca45f580d112f98116cc

npm start        # tsx index.ts
# or: npm run dev  (watch mode)

curl http://localhost:4030/v1/feeds/EIA.PET.PRICE.WTI.DAILY

Related