> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracles

> How offchain data reaches onchain contracts, why oracle design matters, and how Allium derives its own price data.

A blockchain cannot see outside itself. A smart contract can read its own state and other contracts' state, and nothing else — not an exchange price, not an interest rate, not the weather. Every node must reach the same result from the same inputs, so anything that could differ between nodes is off limits.

An **oracle** is the bridge. It is a contract that holds external data, updated by parties who observe the outside world and publish what they see. Everything that needs a price — lending liquidations, perp margin, stablecoin pegs, RWA valuations — depends on one.

## Why this is the hard part

An oracle is the point where a trust-minimized system takes an input on trust. Its data determines who gets liquidated and at what price, so it is the highest-value target in DeFi.

Most large DeFi exploits have been oracle problems rather than contract bugs. The archetype: an attacker moves the price on a thin market the oracle reads, borrows against the manipulated valuation, and leaves with the difference. Nothing in the lending contract malfunctioned — it was correctly told the wrong price.

That is why oracle design is mostly about making manipulation expensive:

| Defence                                | How it works                                                                                         |
| :------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| **Many independent reporters**         | No single node can move the reported value                                                           |
| **Median or trimmed aggregation**      | An extreme outlier is discarded rather than averaged in                                              |
| **Volume-weighted sourcing**           | Deep markets dominate the price; thin ones cannot move it                                            |
| **Time-weighting (TWAP)**              | Manipulating the average requires holding the price off-market for a sustained period, not one block |
| **Deviation and heartbeat thresholds** | Updates when the price moves by more than *x*, or at least every *y* — capping staleness             |
| **Circuit breakers**                   | Reject updates outside a plausible band and pause rather than act on nonsense                        |

## The main designs

| Type             | How it works                                                                                                        | Trade-off                                                                       |
| :--------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------ |
| **Push oracle**  | A network of nodes writes the price onchain on a schedule or on deviation. Chainlink is the canonical example       | Always readable, costs gas continuously, is as fresh as the last update         |
| **Pull oracle**  | The consumer fetches a signed price offchain and submits it with their transaction. Pyth and Redstone work this way | Fresher and cheaper, but pushes the fetch step into the caller                  |
| **Onchain TWAP** | Reads the time-weighted average from an AMM pool's own accumulator. Uniswap v2 and v3 expose this                   | Fully onchain and trust-free, but lags, and inherits the pool's liquidity depth |
| **First-party**  | The venue publishes its own mark and index prices                                                                   | Authoritative for that venue, and only for that venue                           |

<Note>
  A perp venue's **index price** is an oracle output; its **mark price** is not. Mark is derived from the venue's own order book with a bounded premium to the index. Using mark as a spot reference will show you the venue's basis, not the market price. See [Perpetuals](/guides/perpetuals).
</Note>

## How Allium prices assets

Allium is not an oracle — nothing onchain reads from us, and we do not publish a feed contracts consume. We build price data for analysis, which frees us from the constraints an onchain oracle works under: we can look across every venue at once, revise a price when better information arrives, and be right retrospectively rather than only in the moment.

| Dataset                                                                                    | How it is built                                                                  | Use it for                                 |
| :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | :----------------------------------------- |
| [`common.prices.hourly`](/historical-data/prices/token-prices-hourly)                      | Hourly prices per token and chain, blending DEX and centralized-exchange sources | The default for valuing holdings and flows |
| [`common.prices.dex_token_prices_hourly`](/historical-data/prices/dex-token-prices-hourly) | Derived from DEX trades alone                                                    | Long-tail tokens that no exchange lists    |
| [CEX data](/historical-data/cex)                                                           | Per-venue OHLCV and cross-venue VWAP                                             | Venue-level and reference pricing          |
| [Realtime prices](/api/developer/overview)                                                 | Prices computed from trades at the chain tip                                     | Live pricing in an application             |

<Warning>
  A long-tail token's price is only as meaningful as the liquidity behind it. A token whose entire market is one shallow pool can print a price from a few dollars of volume, and that price is real in the sense that a trade happened at it, and unusable as a valuation. Check the pool depth and trade volume alongside the price before you value a position with it.
</Warning>

## Next steps

* [Prices](/historical-data/prices) — the full price data vertical
* [AMMs vs CLOBs](/guides/amms-vs-clobs) — where DEX-derived prices come from
* [MEV](/guides/mev) — oracle updates are themselves a target for ordering games