Choose a method

Every Claros value lives on-chain on Casper, keyed by a feed_id string. Reading that data is free. There are four ways to read a feed, and they all resolve to the same underlying on-chain reading. The right one depends on where your code runs: a backend, a browser, another Casper contract, or a metered pay-per-call endpoint.

At a glance

Which one fits

• Reading from a server or script? Use the REST API for any language, or the SDK if you are already in TypeScript.
• Reading from another Casper contract? Use a cross-contract call. It is the only on-chain path and costs only gas.
• Want a hosted, metered endpoint you can sell or buy per call? Use x402. It is the paid path, settled in WCSPR.

The same read, three free ways

The three free methods return the same reading for the same feed_id. Here is EIA.PET.PRICE.WTI.DAILY (WTI crude oil daily spot price) read each way. The Quickstart walks through the full example.

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

// inside your Odra module, with the AttestationRegistry package hash as `registry`:
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^decimals

The four methods

REST API

services/claros-api is an Express service (default port 4030) that reads Casper on-chain state through the SDK and serves it as JSON. GET /v1/feeds lists every live feed with metadata and its latest value, GET /v1/feeds/:id returns one full reading, and GET /v1/datasets?q=&family= searches the EIA discovery catalog. Each reading carries feed_id, value, amount (a string, U512-safe), decimals, unit, title, source, route, frequency, period, source_hash, and updated_at. No key, no wallet, no indexer. This is the best fit for apps, dashboards, bots, and AI agents in any language. Read more on the REST API page.

TypeScript SDK

The claros-oracle npm package (v0.1.0) reads Casper global state directly over JSON-RPC, with the testnet contract addresses baked in. Construct new ClarosOracle(cfg?), then call getReading(id) for a full typed Reading, getValue(id) and getFeed(id) for the value and metadata separately, or feedCount(), feedIdAt(i), and listFeedIds() to enumerate every feed. There is no server to run and no indexer to sync. Reading.amount is a bigint (U512-safe) rather than a string. This is the fastest path when your code is already JavaScript or TypeScript. Read more on the SDK page.

Cross-contract

To read Claros from your own Casper contract, declare the registries as external contracts and call AttestationRegistry.get_latest(asset_id: String) -> Option<Attestation> for the value and FeedRegistry.get_feed(feed_id: String) -> Option<Feed> for the metadata. Attestation gives you period, amount (U512), source_hash, attester, and timestamp; Feed gives you decimals, unit, title, source, route, frequency, and description. Compute amount / 10^decimals in-contract. This is the only on-chain path, and it costs gas only with no per-read fee. Read more on the cross-contract page.

x402 metered

services/oracle-server (default port 4021) exposes GET /oracle/feed?asset_id=OP-1 behind the x402 HTTP 402 protocol. This is the paid, hosted, metered path: each call is settled in WCSPR (demo price $0.001, about 1 WCSPR, set by FEED_PRICE_MOTES). The endpoint serves the latest attested reading with on-chain provenance, carrying the same source_hash the agent attests, and the WCSPR lands with the Claros agent. The flow is:

This is how the Claros agent monetizes its data and funds its own attestations. Read more on the x402 page.

Pick a page