Using Data Feeds on Stellar
Stellar is a Layer 1 blockchain that uses Soroban smart contracts written in Rust. Chainlink Data Feeds on Stellar are delivered through Chainlink Runtime Environment (CRE), which publishes data onchain using a decentralized oracle network.
Chainlink Data Feeds on Stellar follow the same pattern as Data Feeds on Aptos: a single cache contract serves every feed, and consumers select a feed by its 32-byte data_id rather than by a per-feed contract address. This contrasts with Chainlink's integration on EVM blockchains, where each price feed has a separate contract address.
A data_id is a 32-byte identifier for a feed, similar to how a contract address identifies a feed on EVM chains. It is the same value as the Feed ID shown in the Price Feed Contract Addresses table. You pass the data_id to the cache contract to read that feed's data.
How Stellar Data Feeds work
Data Feeds on Stellar use a cache contract that the Chainlink oracle network writes into. Consumers read feeds directly from the cache by passing a 32-byte data_id:
- Cache contract: A single cache contract serves every feed. The Chainlink oracle network writes round data into the cache, and consumers read it by passing the
data_idfor the feed they need. The cache address stays stable across upgrades. - Fallback proxy: A separate fallback proxy exists for the DF1 data feed, but it is not customer-facing and is not documented here.
Consumers select a feed by passing its 32-byte data_id to the cache. You can find the data_id for each feed on the Price Feed Contract Addresses page with Stellar selected.
Supported networks
Chainlink Data Feeds are available on the following Stellar networks:
Cache contract addresses
The cache contract address is the same for every feed on a given network. You only ever interact with the cache.
- Stellar Testnet:
CAVLZXJDRGOS6UZ7BHYTYW7STQMZIOCUJIVRMT7JE7T5F6JIA3LPAOVW - Stellar Mainnet (Pubnet):
CAAFKBE6AMTERARISMMT4TCC4UGNO35XCKQNC5XVLL5WY5GRWXH6AMIO
Reader interface
Consumers call the following functions on the cache contract. The interface is defined in the chainlink-stellar repository.
| Function | Returns |
|---|---|
latest_round(data_ids) | The most recent round for each requested data_id |
get_round(data_id, round_id) | A specific historical round |
decimals(data_ids) | Decimal places for each requested data_id |
description(data_ids) | Human-readable pair name for each requested data_id |
Round structure
A round returned by the cache carries the following fields:
| Field | Description |
|---|---|
round_id | The unique identifier of the round |
answer | The answer for the feed, represented as an I256 |
timestamp | The Unix timestamp in seconds when the round was recorded |
ledger_seq | The Stellar ledger sequence at which the round was recorded |
primary | Indicates whether the round is the primary round for the feed |
Error handling
When you call the cache, the contract can return a CacheError. The following cases describe what each error means for a consumer:
| Error | Meaning |
|---|---|
FeedNotConfigured | The data_id you passed does not correspond to a configured feed. Check that you are using the correct data_id from the Price Feed Contract Addresses page with Stellar selected. |
InvalidDataId | The data_id you passed is invalid. |
FeedFrozen | The feed is frozen and cannot be read. |
How long a round is available
A round is stored in the cache contract's temporary storage with a retention period of 3,110,400 ledgers. After this period, a round can no longer be read from the cache.
Getting started
You can read Chainlink Data Feeds on Stellar either onchain or offchain:
- Onchain: Deploy a Soroban contract in Rust that calls the cache and reads a price, deployed with
stellar-clito the Stellar Testnet. - Offchain: Read a feed via Soroban RPC simulation using
stellar-cliand the Stellar JavaScript SDK.
Answer precision
The cache stores every answer at a fixed 18 decimal places (DECIMALS). Feeds sourced at a lower precision, such as 8 decimals, are scaled up to 18 on write, so the stored value is always 18-decimal regardless of the feed's native precision. When you read a round, the answer is returned at 18 decimal places.