Read data feeds with API3

You want to read a live price (or other off-chain data) feed from API3 into a contract on Lumia.

Who this is for: developers building a contract that needs an oracle-sourced value. Prerequisites: Oracles & Attestation (concept) for what an oracle is and how it differs from attestation (this page doesn't re-explain that); Networks & Endpoints. Time: varies, depending on whether a proxy for the feed you need is already deployed on the network you're targeting.

API3 is named in Lumia's documentation as an integrated oracle provider.

How the integration mechanism generally works

API3's dAPIs are read directly from an on-chain proxy contract. There's no separate off-chain relayer call for the read path; your contract calls the proxy's read function and gets back a value and a timestamp.

Steps

1

Confirm whether a dAPI proxy is already deployed

On the Lumia network you're targeting (mainnet or Beam). Do not substitute a proxy address from API3's docs for another chain. A proxy address is chain-specific.

2

Call the proxy's read function

Once you have a confirmed proxy address, add it to your project and call its read function to get the current value and timestamp.

3

Check the timestamp

Check the returned timestamp against your own freshness requirement before trusting the value. This is a standard oracle-consumption pattern, not Lumia-specific.

Verify it worked

Once you have a real proxy address, a read call should return a non-zero value and a recent timestamp; cross-check the value against a second source before relying on it in production.

Troubleshooting

No proxy address to call

Confirm the proxy address with API3 or Lumia directly for the network you're targeting; do not substitute an address from a different chain's API3 deployment.

Stale timestamp

API3's dAPIs are pushed on data-provider triggers, not a fixed schedule; a stale read may mean the underlying value genuinely hasn't moved, not that something is broken.