> For the complete documentation index, see [llms.txt](https://docs.greenowl.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.greenowl.money/interfaces/interfaces/ioracleadapter.md).

# IOracleAdapter

**Interface for price oracle adapters used in Owl Smart Wallet DeFi integrations**

## Overview

`IOracleAdapter` defines a standardized interface for fetching asset prices from various oracle sources (Chainlink, Pyth, Chronicle, etc.). This interface is used by DeFi adapters like `OwlLendingAdapter` to obtain real-time price data for collateral valuation, liquidation checks, and risk assessment.

The interface provides:

* **Unified price query** — `getPrice()` returns a structured `PriceData` object with validity checks
* **Chainlink compatibility** — `getLatestRoundData()` mirrors Chainlink's aggregator interface for drop-in replacement
* **Staleness detection** — Built-in checks for stale prices, sequencer downtime, and price deviation

**Role in the system:**

* Used by **OwlLendingAdapter** to validate collateral and check liquidation thresholds
* Enables **AI agents** to make informed DeFi decisions using fresh, validated price data
* Supports **multi-oracle strategies** (fallback oracles, median aggregation, etc.)

***

## Functions

### getPrice

Gets the current price of an asset with validity checks.

```solidity
function getPrice(address asset) external view returns (PriceData memory data);
```

**Parameters**

| Name    | Type      | Description                                          |
| ------- | --------- | ---------------------------------------------------- |
| `asset` | `address` | The address of the asset to price (e.g., WETH, USDC) |

**Returns**

| Name   | Type        | Description                                    |
| ------ | ----------- | ---------------------------------------------- |
| `data` | `PriceData` | Structured price data with validity indicators |

**Usage**

This is the primary method for obtaining asset prices. Always check `data.isValid` before using the price. If invalid, inspect `data.reason` for details (e.g., `"STALE"`, `"DEVIATED"`, `"SEQUENCER_DOWN"`).

**Access Control**

View function — callable by anyone.

***

### getLatestRoundData

Gets the latest round data from the underlying oracle (Chainlink compatibility mode).

```solidity
function getLatestRoundData(address asset)
    external
    view
    returns (
        uint80 roundId,
        int256 answer,
        uint256 startedAt,
        uint256 updatedAt,
        uint80 answeredInRound
    );
```

**Parameters**

| Name    | Type      | Description              |
| ------- | --------- | ------------------------ |
| `asset` | `address` | The address of the asset |

**Returns**

| Name              | Type      | Description                                         |
| ----------------- | --------- | --------------------------------------------------- |
| `roundId`         | `uint80`  | The round identifier                                |
| `answer`          | `int256`  | The price answer (may be negative for some oracles) |
| `startedAt`       | `uint256` | Round start timestamp                               |
| `updatedAt`       | `uint256` | Round update timestamp                              |
| `answeredInRound` | `uint80`  | The round in which the answer was computed          |

**Usage**

Provides Chainlink-compatible output for systems expecting the standard aggregator interface. For new integrations, prefer `getPrice()` which includes built-in validity checks.

**Access Control**

View function — callable by anyone.

***

## Structs

### PriceData

Price information returned by the oracle adapter.

```solidity
struct PriceData {
    uint256 price;      // scaled to 1e8 (or adapter-specific decimals)
    uint256 updatedAt;  // Unix timestamp of last update
    bool isValid;       // false if stale/deviated/unavailable
    uint8 decimals;     // number of decimals for price field
    bytes32 reason;     // reason code when isValid == false
}
```

**Fields**

| Name        | Type      | Description                                                                                      |
| ----------- | --------- | ------------------------------------------------------------------------------------------------ |
| `price`     | `uint256` | The asset price scaled to `decimals` precision (typically 1e8 for USD prices)                    |
| `updatedAt` | `uint256` | Unix timestamp when the price was last updated by the oracle                                     |
| `isValid`   | `bool`    | `true` if price is fresh and valid; `false` if stale, deviated, or unavailable                   |
| `decimals`  | `uint8`   | Number of decimals used for the `price` field (usually 8 for USD pairs)                          |
| `reason`    | `bytes32` | Optional reason code when `isValid == false` (e.g., `"STALE"`, `"DEVIATED"`, `"SEQUENCER_DOWN"`) |

**Reason Codes**

Common values for `reason`:

* `"STALE"` — Price hasn't been updated within the acceptable window
* `"DEVIATED"` — Price deviates beyond acceptable threshold from fallback oracle
* `"SEQUENCER_DOWN"` — L2 sequencer is down (Arbitrum/Optimism)
* `0x0` (empty) — Price is valid

**Usage**

Always check `isValid` before using `price`. If invalid, the price should not be trusted for critical operations like liquidations or collateral valuation.

***

## Implementation Notes

**For Oracle Adapter Implementers:**

* Must implement both `getPrice()` and `getLatestRoundData()` for compatibility
* Should perform staleness checks (e.g., Chainlink heartbeat thresholds)
* Must handle L2 sequencer uptime feeds when applicable
* Should revert on zero/negative prices or set `isValid = false` with appropriate reason code

**For DeFi Adapter Consumers:**

* Always validate `isValid` before using price data
* Implement fallback logic for invalid prices (e.g., pause operations, use backup oracle)
* Consider implementing circuit breakers for repeated invalid prices
* Log `reason` codes for monitoring and alerting


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.greenowl.money/interfaces/interfaces/ioracleadapter.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.