# Current oracle state and recent confirmed history

`GET /oracles/{feedId}` · Lithos client API · Oracle Feeds

Source: https://lithosprotocol.org/docs/api/get-oracle-feed

The confirmed pool NFT box, its exact R4 raw rate and R5 epoch, converted price, age and recent history. USD v2 stores nanoERG per USD; USD per ERG is `1000000000 / rawValue`. The displayed price is rounded to 18 decimal places; `priceNumerator / priceDenominator` preserves the exact rational conversion. Current and history boxes must match the configured NFT, guard hash and register types. History is newest first, including the current point on the first page, and defaults to the latest 100 confirmed pool updates. Set `limit=0` for current state only. Offsets count NFT boxes, including governance transitions and the initial zero-price bootstrap box, which is omitted from price points. Follow `nextOffset` and pass the returned `blockId` as `atBlockId` to keep pagination on the same tip. `stale` uses creation-height age and the configured `maxAgeBlocks`, not wall-clock market freshness. Timestamps are confirmed block timestamps when available; missing ones are omitted and reported by `timestampsComplete=false`. A lagging index or unavailable/unsupported pool is 503; a tip change is 409.

## Parameters

| Name | In | Type | Required | Description |

|---|---|---|---|---|

| `feedId` | path | string | yes |  |

| `offset` | query | integer | no |  |

| `limit` | query | integer | no |  |

| `atBlockId` | query | string | no | Optional tip id returned by the preceding page; a changed tip requires pagination to restart. |

## Responses

### 200: Confirmed node snapshot; a stale published price is returned with `stale=true`.

`OracleState`

- `feed` (OracleFeed, required)
  - `id` (string, required)
  - `name` (string, required)
  - `network` (string, required, one of MAINNET, TESTNET)
  - `protocol` (string, required)
  - `poolNft` (string, required)
  - `ergoTreeHash` (string, required): Configured full ErgoTree blake2b256. Governance changes require review of this pin.
  - `baseAsset` (string, required)
  - `quoteAsset` (string, required)
  - `rawUnit` (string, required)
  - `priceUnit` (string, required)
  - `baseDecimals` (integer, required)
  - `maxAgeBlocks` (integer, required)
- `height` (integer, required)
- `blockId` (string, required)
- `indexedHeight` (integer, required)
- `current` (OraclePoint, required)
  - `boxId` (string, required)
  - `transactionId` (string, required)
  - `creationHeight` (integer, required): Height committed by the pool box; used to compute ageBlocks.
  - `inclusionHeight` (integer, required)
  - `epoch` (integer, required)
  - `rawValue` (string, required): Exact positive R4 Long in the feed's rawUnit.
  - `price` (string, required): Converted quote units per base unit, rounded to 18 decimal places.
  - `priceNumerator` (string, required)
  - `priceDenominator` (string, required)
  - `ergoTreeHash` (string, required)
  - `timestamp` (integer · int64): Inclusion block timestamp in milliseconds, omitted if unavailable.
- `ageBlocks` (integer, required)
- `stale` (boolean, required): ageBlocks exceeds the configured maxAgeBlocks; no wall-clock freshness is implied.
- `history` (OraclePoint[], required)
- `offset` (integer, required)
- `limit` (integer, required)
- `total` (integer): Indexed NFT box count, including the bootstrap box; omitted with limit=0.
- `nextOffset` (integer): Next NFT-box offset, absent at the end or when history is omitted.
- `timestampsComplete` (boolean, required)

### 400: Invalid paging or block id.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 404: No configured feed with this id on the node's network.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 409: Chain tip changed; retry the snapshot or restart pagination.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 503: Node, index, oracle identity or supported pool state unavailable.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

## Example request

```bash
curl -X GET "http://localhost:9000/oracles/{feedId}"
```

## Example response

```json
{
  "feed": {
    "id": "erg-usd",
    "name": "USD v2",
    "network": "MAINNET",
    "protocol": "oracle-pool-v2",
    "poolNft": "string",
    "ergoTreeHash": "string",
    "baseAsset": "ERG",
    "quoteAsset": "USD",
    "rawUnit": "nanoERG/USD",
    "priceUnit": "USD/ERG",
    "baseDecimals": 9,
    "maxAgeBlocks": 30
  },
  "height": 0,
  "blockId": "string",
  "indexedHeight": 0,
  "current": {
    "boxId": "string",
    "transactionId": "string",
    "creationHeight": 0,
    "inclusionHeight": 0,
    "epoch": 0,
    "rawValue": "string",
    "price": "string",
    "priceNumerator": "string",
    "priceDenominator": "string",
    "ergoTreeHash": "string",
    "timestamp": 0
  },
  "ageBlocks": 0,
  "stale": true,
  "history": [
    {
      "boxId": "string",
      "transactionId": "string",
      "creationHeight": 0,
      "inclusionHeight": 0,
      "epoch": 0,
      "rawValue": "string",
      "price": "string",
      "priceNumerator": "string",
      "priceDenominator": "string",
      "ergoTreeHash": "string",
      "timestamp": 0
    }
  ],
  "offset": 0,
  "limit": 0,
  "total": 0,
  "nextOffset": 0,
  "timestampsComplete": true
}
```