> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/trading/trading/perpetuals/price-oracles.md).

# Price oracles

How the mark and index prices are built, and the freshness and deviation guards on them.

Every perpetual market is priced by an external oracle that produces a **mark price** and **index price**. These drive margin and liquidation. They are decoupled from the last trade on the order book by design, so thin-book activity cannot distort risk calculations.

Funding is the exception, by design. It is priced off the **perp reference price** (the volume-weighted median of recent trades on our book) measured against the index. The mark is 95% index by construction, so measuring against it would understate the perpetual's real deviation by roughly 20×. See Funding Rates.

### Sources

**The source is per-market configuration, not one venue-wide feed.** It changes as feeds are evaluated and cut over, so rely on the modes below rather than on any particular vendor name.

Each market is configured in one of three modes:

| Mode              | Behaviour                                                               |
| ----------------- | ----------------------------------------------------------------------- |
| **Single source** | One configured publisher. If it goes stale, the market has no fallback  |
| **Failover**      | A primary publisher with a named fallback, as an ordered chain          |
| **Synthetic**     | A derived price, used where no external publisher covers the underlying |

**The configured 32-market set and the deployed set do not have the same source profile, and it is easy to mistake the first for the second.** Most of the configured markets name a single source. The deployed markets have been moved over time onto **failover chains with a Pyth primary**, which is the opposite emphasis. Do not infer a market's source from a count across the config.

For the current source and mode of a specific market, read `GET /markets/{market_id}/risk-params` rather than assuming.

Each market's mark price is published into the engine through an internal oracle service; the engine itself never makes outbound network calls on the trading path.

### Freshness and deviation guards

Each market is configured with two protective thresholds (per-market, in the engine config):

| Guard         | Current testnet value                    | Behavior                                                                     |
| ------------- | ---------------------------------------- | ---------------------------------------------------------------------------- |
| **Staleness** | `oracle_staleness_seconds = 30`          | A feed older than the threshold is treated as stale.                         |
| **Deviation** | `oracle_deviation_threshold = 0.1` (10%) | A single update that jumps more than the threshold is rejected as anomalous. |

A monotonic timestamp guard (`ts ≥ last_update_time`) rejects out-of-order updates, so a delayed packet cannot overwrite a newer price.

### Fail-closed direction

The oracle is being hardened to **fail closed**: when a feed is stale or fails its guards, the safe behavior is to pause new risk-increasing actions in that market rather than trade on a suspect price. Staleness handling and multi-source fallback are being strengthened across the current release gates.

**Beyond the oracle's own guards, the venue bounds prices twice more**: an order-versus-mark collar and a max-move circuit breaker, both armed on every market. [Discovery bounds](/trading/trading/perpetuals/discovery-bounds.md) documents both.

The mark-price blend, the re-anchoring rule and the staleness guards are derived formally in the [Math Engine's oracle chapter](https://docs.nexus.xyz/math-engine/oracle). For a dated record of which markets have had their source changed, and how often, see [Parameter changes](/consolidated-resources/parameter-changes.md).

> **Status:** oracle integration is live on testnet with the guards above. Per-market failover is deployed on part of the live set; the source assignment for each market is configuration and is still being tuned, so treat a specific vendor pairing as current rather than settled.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexus.xyz/trading/trading/perpetuals/price-oracles.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.