# Price feeds
Source: https://docs.settlemint.com/docs/api-reference/feeds/price-feeds
Read the on-chain price-feed registry through DALP. List registered feeds, read one feed, resolve a feed for a subject and topic, and inspect latest value, historical rounds, and staleness.
A bank that values tokenized assets needs to know which price feed backs each asset, what the feed last reported, and whether that value is fresh enough to act on. The price-feed registry answers those questions. It tracks every feed registered for the system, the subject and topic each feed prices, and the latest signed value the feed produced.
The read endpoints under `/api/v2/system/feeds` return DALP response envelopes and use the shared collection query format for lists. Feed registration, replacement, and value submission are governance operations outside the scope of this reference.
For fiat currency pair rates such as `EUR / USD`, use the [exchange rates API](/docs/api-reference/feeds/exchange-rates), which resolves one rate per pair on top of these feeds.
## Endpoints [#endpoints]
| Job | Method and path | Use it for | Response shape |
| ------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| List feeds | `GET /api/v2/system/feeds` | Discover registered feeds with their subject, topic, decimals, scope, and latest value. | Collection envelope with `data`, `meta`, and `links`. |
| Read one feed | `GET /api/v2/system/feeds/{feedAddress}` | Read full details for one feed by its contract address. | Single-resource envelope with `data` and `links.self`. |
| Read feed configuration | `GET /api/v2/system/feeds/{feedAddress}/config` | Read the immutable settings an issuer-signed feed enforces on every update. | Single-resource envelope with `data` and `links.self`. |
| Resolve a feed | `GET /api/v2/system/feeds/resolve` | Find the feed registered for a subject and topic pair. | Single-resource envelope with `data` and `links.self`. |
| Read feed capabilities | `GET /api/v2/system/feeds/capabilities` | Check whether the feed directory, factories, and adapters are installed. | Single-resource envelope with `data` and `links.self`. |
| Read the latest value | `GET /api/v2/system/feeds/{feedAddress}/latest` | Read the most recent round directly from a feed contract. | Single-resource envelope with `data` and `links.self`. |
| Read a historical round | `GET /api/v2/system/feeds/{feedAddress}/round/{roundId}` | Read one earlier round by its round identifier. | Single-resource envelope with `data` and `links.self`. |
| Evaluate staleness | `GET /api/v2/system/feeds/{feedAddress}/staleness` | Decide whether a feed value is too old to use against an age threshold. | Single-resource envelope with `data` and `links.self`. |
| List issuer-signed feeds | `GET /api/v2/system/feeds/issuer-signed` | List feeds the platform created and signs values for in this system. | Collection envelope with `data`, `meta`, and `links`. |
| List adapter-backed feeds | `GET /api/v2/system/feeds/adapters` | List feeds that publish through a stable adapter address. | Collection envelope with `data`, `meta`, and `links`. |
A feed prices a `subject` for a `topic`. The subject is the address the feed describes, such as a token. The topic identifies what the value means, such as a price in a given currency. A `description` follows the ` / ` convention, so a token price feed reads as `USDT / USD` and a global currency feed reads as `EUR / USD`.
## List registered feeds [#list-registered-feeds]
The list endpoint returns the feeds registered in the system, most recently registered first. Each record carries the feed's identity, its latest indexed value, and whether it is active.
```bash
curl --globoff "https://your-platform.example.com/api/v2/system/feeds?filter[isActive]=true&filter[scope]=asset&page[limit]=50&sort=-registeredAt" \
-H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```
The response uses the collection envelope:
```json
{
"data": [
{
"id": "0x1111111111111111111111111111111111111111",
"feedAddress": "0x1111111111111111111111111111111111111111",
"subject": "0x2222222222222222222222222222222222222222",
"topicId": "1",
"kind": "SCALAR",
"schemaHash": "0x3333333333333333333333333333333333333333333333333333333333333333",
"decimals": 8,
"scope": "asset",
"factory": { "id": "0x4444444444444444444444444444444444444444", "typeId": "issuer-signed-scalar-feed" },
"creator": { "id": "0x5555555555555555555555555555555555555555" },
"adapterAddress": null,
"isActive": true,
"registeredAt": "2026-03-22T10:30:00.000Z",
"latestValue": {
"roundId": 12,
"answer": "100000000",
"observedAt": "2026-03-22T10:30:00.000Z",
"updatedAt": "2026-03-22T10:30:00.000Z",
"issuer": "0x6666666666666666666666666666666666666666",
"signer": "0x7777777777777777777777777777777777777777"
},
"description": "USDT / USD"
}
],
"meta": {
"total": 1,
"facets": {
"kind": [{ "value": "SCALAR", "count": 1 }],
"scope": [{ "value": "asset", "count": 1 }],
"isActive": [{ "value": "true", "count": 1 }]
}
},
"links": {
"self": "/v2/system/feeds?filter[isActive]=true&filter[scope]=asset&page[limit]=50&page[offset]=0&sort=-registeredAt",
"first": "/v2/system/feeds?filter[isActive]=true&filter[scope]=asset&page[limit]=50&page[offset]=0&sort=-registeredAt",
"next": null,
"prev": null,
"last": "/v2/system/feeds?filter[isActive]=true&filter[scope]=asset&page[limit]=50&page[offset]=0&sort=-registeredAt"
}
}
```
`latestValue` is `null` until the feed produces its first round. Read it to learn the feed's most recent answer without a second call. The `answer` is an integer string in feed units: divide it by `10` to the power of `decimals` to get the human value, and use decimal arithmetic rather than binary floating-point in financial workflows.
The `kind`, `scope`, and `isActive` fields are facetable. The `meta.facets` block counts the matching feeds per value, which lets a picker show how many feeds sit behind each option without a separate count query.
## Read one feed [#read-one-feed]
Call the single-feed read when you already hold the feed contract address. It returns the same record shape as a list row.
```bash
curl "https://your-platform.example.com/api/v2/system/feeds/0x1111111111111111111111111111111111111111" \
-H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```
```json
{
"data": {
"id": "0x1111111111111111111111111111111111111111",
"feedAddress": "0x1111111111111111111111111111111111111111",
"subject": "0x2222222222222222222222222222222222222222",
"topicId": "1",
"kind": "SCALAR",
"decimals": 8,
"scope": "asset",
"isActive": true,
"registeredAt": "2026-03-22T10:30:00.000Z",
"latestValue": {
"roundId": 12,
"answer": "100000000",
"observedAt": "2026-03-22T10:30:00.000Z",
"issuer": "0x6666666666666666666666666666666666666666",
"signer": "0x7777777777777777777777777777777777777777"
},
"description": "USDT / USD"
},
"links": {
"self": "/v2/system/feeds/0x1111111111111111111111111111111111111111"
}
}
```
## Read immutable feed configuration [#read-immutable-feed-configuration]
An issuer-signed feed fixes its trust and validation rules at creation, and the contract enforces them on every signed update. Read its configuration before you accept a feed's value into a valuation or settlement workflow. The response confirms what the feed actually guarantees:
* which subject and topic it prices,
* the schema hash its values must match,
* whether it rejects non-positive answers,
* how far ahead of block time a value's timestamp may sit,
* and which trusted-issuer and topic-scheme registries it checks signatures against.
These settings cannot change after deployment, so this read is the source for an auditor or risk reviewer verifying a feed's controls.
```bash
curl "https://your-platform.example.com/api/v2/system/feeds/0x1111111111111111111111111111111111111111/config" \
-H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```
```json
{
"data": {
"feedAddress": "0x1111111111111111111111111111111111111111",
"subject": "0x2222222222222222222222222222222222222222",
"topicId": "1",
"expectedSchemaHash": "0x3333333333333333333333333333333333333333333333333333333333333333",
"decimals": 8,
"description": "USDT / USD",
"historyMode": "FULL",
"historySize": 0,
"requirePositive": true,
"driftAllowance": 0,
"domainSeparator": "0x8888888888888888888888888888888888888888888888888888888888888888",
"trustedIssuersRegistry": "0x9999999999999999999999999999999999999999",
"topicSchemeRegistry": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"links": { "self": "/v2/system/feeds/0x1111111111111111111111111111111111111111/config" }
}
```
`requirePositive` set to `true` means the feed rejects zero and negative answers. `driftAllowance` is the maximum number of seconds an update's `observedAt` timestamp may sit ahead of the chain's block time, which tolerates small signer clock skew; `0` requires the timestamp to be at or before block time. `historyMode` and `historySize` describe how many past rounds the feed retains: `LATEST_ONLY` keeps only the current round, `BOUNDED` keeps up to `historySize` rounds, and `FULL` keeps the complete history. The feed validates each update signature against `trustedIssuersRegistry`. At feed creation the factory derives the schema hash from `topicSchemeRegistry` and pins it as `expectedSchemaHash`; per-update enforcement compares the update schema hash to that pinned value, not to the live registry. Those addresses tell you which authorities the feed trusts. This endpoint serves issuer-signed scalar feeds; a feed address that does not resolve to one returns a not-found error.
## Resolve a feed for a subject and topic [#resolve-a-feed-for-a-subject-and-topic]
When you know what you want to price but not which feed serves it, resolve the feed by its subject and topic. Pass `subject` with either `topicName` or `topicId` (or both).
```bash
curl --globoff "https://your-platform.example.com/api/v2/system/feeds/resolve?subject=0x2222222222222222222222222222222222222222&topicId=1" \
-H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```
```json
{
"data": {
"exists": true,
"feedAddress": "0x1111111111111111111111111111111111111111",
"kind": "SCALAR",
"schemaHash": "0x3333333333333333333333333333333333333333333333333333333333333333",
"adapterAddress": null,
"indexed": {
"decimals": 8,
"registeredAt": "2026-03-22T10:30:00.000Z",
"latestValue": {
"roundId": 12,
"answer": "100000000",
"observedAt": "2026-03-22T10:30:00.000Z",
"issuer": "0x6666666666666666666666666666666666666666",
"signer": "0x7777777777777777777777777777777777777777"
}
}
},
"links": {
"self": "/v2/system/feeds/resolve?subject=0x2222222222222222222222222222222222222222&topicId=1"
}
}
```
When no feed is registered for the pair, `exists` is `false` and `feedAddress`, `kind`, `schemaHash`, `adapterAddress`, and `indexed` are `null`. The `indexed` block is also `null` for a registered feed the index has not yet enriched. Read `exists` before you trust the rest of the record.
## Read the latest value and historical rounds [#read-the-latest-value-and-historical-rounds]
The latest and round endpoints read directly from the feed contract, so they return on-chain data exactly as the contract reports it. The latest endpoint returns the most recent round with a `formattedAnswer` already converted into human units.
```bash
curl "https://your-platform.example.com/api/v2/system/feeds/0x1111111111111111111111111111111111111111/latest" \
-H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```
```json
{
"data": {
"feedAddress": "0x1111111111111111111111111111111111111111",
"roundId": "12",
"answer": "100000000",
"decimals": 8,
"formattedAnswer": "1.00000000",
"startedAt": "2026-03-22T10:29:50.000Z",
"updatedAt": "2026-03-22T10:30:00.000Z",
"answeredInRound": "12",
"description": "USDT / USD",
"version": "1"
},
"links": { "self": "/v2/system/feeds/0x1111111111111111111111111111111111111111/latest" }
}
```
Pass a round identifier to read one earlier round. The `roundId` path parameter is a non-negative integer string.
```bash
curl "https://your-platform.example.com/api/v2/system/feeds/0x1111111111111111111111111111111111111111/round/11" \
-H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```
```json
{
"data": {
"roundId": "11",
"answer": "99950000",
"startedAt": "2026-03-22T09:29:50.000Z",
"updatedAt": "2026-03-22T09:30:00.000Z",
"answeredInRound": "11"
},
"links": { "self": "/v2/system/feeds/0x1111111111111111111111111111111111111111/round/11" }
}
```
## Evaluate staleness [#evaluate-staleness]
A valuation workflow should reject a price that is too old. Pass `maxAgeSeconds`, the longest age you will accept, and the endpoint compares the latest round timestamp against the current platform time.
```bash
curl --globoff "https://your-platform.example.com/api/v2/system/feeds/0x1111111111111111111111111111111111111111/staleness?maxAgeSeconds=3600" \
-H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```
```json
{
"data": {
"feedAddress": "0x1111111111111111111111111111111111111111",
"latestUpdatedAt": "2026-03-22T10:30:00.000Z",
"currentTimestamp": "2026-03-22T10:45:00.000Z",
"ageSeconds": 900,
"maxAgeSeconds": 3600,
"isStale": false,
"roundId": "12",
"answer": "100000000"
},
"links": { "self": "/v2/system/feeds/0x1111111111111111111111111111111111111111/staleness?maxAgeSeconds=3600" }
}
```
`isStale` is `true` when `ageSeconds` is greater than `maxAgeSeconds`. Read `isStale` as the decision and `ageSeconds` as the supporting evidence.
## List by creation path [#list-by-creation-path]
Two narrower list endpoints split feeds by how they publish values. Both use the same collection envelope as the main list endpoint.
* `GET /api/v2/system/feeds/issuer-signed` returns feeds the platform created through its factory and signs values for. Each record carries `feedAddress`, `subject`, `topicId`, and `creator`.
* `GET /api/v2/system/feeds/adapters` returns feeds that publish through a stable adapter address, which keeps a fixed consumer address while the underlying source changes. Each record carries `adapterAddress`, `subject`, and `topicId`.
Use the main list endpoint when you want the full feed record with the latest value; use these two when you only need to enumerate feeds by their publishing mechanism.
## Read feed capabilities [#read-feed-capabilities]
The capabilities endpoint reports whether the feed directory, factories, and adapter factory are installed for the system. Read it before you assume the feed endpoints will return data, since an organization can run without the feed modules installed.
```bash
curl "https://your-platform.example.com/api/v2/system/feeds/capabilities" \
-H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"
```
## Parameters and fields [#parameters-and-fields]
| Field | Location | Type | Notes |
| ----------------- | --------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `feedAddress` | Path or filter | EVM address | Feed contract address. The list endpoint supports `filter[feedAddress]`. |
| `roundId` | Path | integer string | Round identifier on the historical round read. |
| `maxAgeSeconds` | Query | positive integer | Longest acceptable value age on the staleness read. |
| `subject` | Query or field | EVM address | Address the feed prices, such as a token. Required on resolve and supported as a list filter. |
| `topicId` | Query or field | numeric string | Topic identifier for the priced value. Supply `topicId` or `topicName` on resolve. |
| `topicName` | Query | string | Topic name alternative to `topicId` on resolve. |
| `kind` | Filter or field | `SCALAR` | Feed value kind. Facetable on the list endpoint. |
| `scope` | Filter or field | `global`, `identity`, `asset`, `other` | What the feed prices. Facetable on the list endpoint. |
| `isActive` | Filter or field | boolean | Whether the feed is currently active. Facetable on the list endpoint. |
| `decimals` | Filter or field | integer | Decimal places for `answer`. Divide `answer` by `10` to the power of `decimals`. |
| `description` | Field | string or `null` | ` / ` label such as `USDT / USD`. |
| `latestValue` | Field | object or `null` | Most recent indexed round: `roundId`, `answer`, `observedAt`, `issuer`, `signer`. `null` before the first round. |
| `answer` | Field | integer string | Reported value in feed units. Apply `decimals` to read the human value. |
| `formattedAnswer` | Field | decimal string | Latest value already converted into human units on the latest read. |
| `isStale` | Field | boolean | Staleness decision: `true` when `ageSeconds` exceeds `maxAgeSeconds`. |
| `requirePositive` | Field | boolean | Whether the feed rejects zero and negative answers. Returned by the config read. |
| `driftAllowance` | Field | integer | Seconds an update timestamp may lead block time. `0` requires it at or before block time. Returned by config. |
| `historyMode` | Field | `LATEST_ONLY`, `BOUNDED`, `FULL` | Number of past rounds the feed retains. Returned by the config read. |
| `exists` | Field | boolean | Whether resolve found a registered feed for the subject and topic. |
| `filter[q]` | Query | string | Free-text search across feed address, subject, topic, and description on the list endpoint. |
| `page[limit]` | Query | integer | Page size for collection responses. |
| `page[offset]` | Query | integer | Offset for collection responses. |
| `sort` | Query | string | Sort field. Prefix with `-` for descending order, such as `sort=-registeredAt`. |
## Related pages [#related-pages]
* [Exchange rates](/docs/api-reference/feeds/exchange-rates) resolves one fiat rate per currency pair on top of these feeds.
* [Token price resolution](/docs/api-reference/tokens/token-price-resolution) explains how token pricing combines base-price and currency feeds.
* [Operational integration patterns](/docs/api-reference/reference/operational-integration-patterns) covers retries, readback checks, and reconciliation around API integrations.