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

# Oracle & Forward Pricing

> Pyth Network spot prices for settlement fixing + publisher-submitted forward prices for position entry and PnL — 18-decimal precision, per-tenor rounds, staleness-based validity

The protocol uses two types of prices: **spot prices** from Pyth Network and **forward prices** computed using interest rate parity. Together they power position entry, PnL tracking, and settlement.

## Two Price Sources

<Columns cols={2}>
  <Card title="Spot Price" icon="satellite-dish">
    The current EUR/USD exchange rate, sourced from Pyth Network. Pyth aggregates prices from institutional publishers (exchanges, market makers, trading firms) and provides a confidence-weighted median.

    **Used for:** Recording the fixing price at maturity for settlement.
  </Card>

  <Card title="Forward Price" icon="chart-line">
    The projected EUR/USD rate at a future maturity date. Forward prices reflect the interest rate differential between EUR and USD — when USD rates are higher than EUR rates, the forward price trades above spot.

    **Used for:** Position entry strikes, real-time PnL calculations, early termination, liquidation.
  </Card>
</Columns>

## How Forward Prices Work

In traditional FX markets, forward prices differ from spot because of the interest rate differential between currencies. If you can earn more interest holding USD than EUR, the forward EUR/USD rate will be slightly higher than spot to reflect this "carry" advantage.

The protocol models this using a simple interest rate parity formula:

```
Forward Price = Spot × (1 + rate × time / year)
```

Where:

* **Spot** is the current EUR/USD price from Pyth
* **rate** is the annualized interest rate differential (configurable)
* **time** is the seconds remaining until maturity
* **year** is 365 days in seconds (31,536,000)

<Accordion title="Worked example: 30-day forward">
  **Inputs:**

  * EUR/USD spot: 1.0800
  * Interest rate differential: 2% annualized
  * Time to maturity: 30 days

  **Calculation:**

  ```
  premium = 1.0800 × 2% × (30/365)
          ≈ 0.00178

  Forward = 1.0800 + 0.00178 = 1.08178
  ```

  The forward is about 18 pips above spot, reflecting the 2% annualized rate differential prorated over 30 days.
</Accordion>

<Info>
  Longer tenors produce larger forward premiums because there is more time for the interest rate differential to compound. A 1-month forward has roughly 30x the premium of a 1-day forward, all else equal.
</Info>

## The Fixing Price

The fixing price is the settlement anchor for matured positions. It is the Pyth EUR/USD spot price captured at **4:00 PM UTC** on the maturity business day.

<Steps>
  <Step title="Maturity date arrives">
    When your position's maturity date is reached, a fixing price needs to be recorded for that timestamp.
  </Step>

  <Step title="Pyth spot price is captured">
    The spot price from Pyth within a ±2 minute window of the fixing time (4 PM UTC) is recorded onchain. Once recorded, the fixing price is permanent.
  </Step>

  <Step title="Settlement uses the fixing price">
    Your final PnL is calculated using the fixing price (not the forward price). All positions maturing at the same timestamp settle against the same fixing price.
  </Step>
</Steps>

<Note>
  The fixing time of 4 PM UTC aligns with the ECB's EUR/USD reference rate, which is the standard benchmark in institutional FX markets.
</Note>

## Price Staleness

Both spot and forward prices have freshness requirements. Stale prices are considered invalid and cannot be used for trading.

| Price Type | Maximum Age | What Happens When Stale               |
| ---------- | ----------- | ------------------------------------- |
| Forward    | 60 seconds  | Position opens and PnL lookups revert |
| Spot       | 30 seconds  | Fixing price recording may fail       |

When forward prices become stale, the protocol can automatically transition to Degraded or Paused mode, blocking new positions until fresh prices are available. See [Mode Escalation](/protocol/mode-escalation) for details.

## Oracle Safeguards

Published forward prices pass through multiple safeguard checks before being accepted:

| Safeguard                                                   | What It Prevents                          |
| ----------------------------------------------------------- | ----------------------------------------- |
| **Update spacing** (min 10s between updates)                | Rapid-fire price manipulation             |
| **Move limit** (max 2% per update)                          | Flash crash or single-update manipulation |
| **Deviation vs prior** (max 0.5% from last accepted)        | Cumulative price drift                    |
| **Deviation vs last close** (max 1.5% from last settlement) | Divergence from settlement prices         |

These safeguards work together as defense-in-depth — a price must pass all four checks to be accepted. For the full technical details, see [Oracle Safeguards](/protocol/oracle-safeguards).

<Warning>
  If all safeguard checks are failing (e.g., during extreme market volatility), forward prices cannot be updated and will become stale. This triggers mode escalation to protect open positions.
</Warning>

## How Prices Affect Your Position

| Event                 | Price Used                                  | Source             |
| --------------------- | ------------------------------------------- | ------------------ |
| Opening a trade       | Forward price for your maturity date        | Oracle (publisher) |
| Real-time PnL display | Latest forward price for your maturity date | Oracle (publisher) |
| Early termination     | Latest forward price for your maturity date | Oracle (publisher) |
| Liquidation check     | Latest forward price for your maturity date | Oracle (publisher) |
| Maturity settlement   | Fixing price (Pyth spot at 4 PM UTC)        | Pyth Network       |

<Tip>
  Your entry price and the current forward price determine your unrealized PnL. But at maturity, settlement uses the Pyth spot price (fixing price), not the forward price. The forward premium converges to zero as maturity approaches, so for held-to-maturity positions, the difference is minimal.
</Tip>

## Next Steps

<Columns cols={3}>
  <Card title="PnL Calculation" icon="calculator" href="/protocol/pnl">
    How profit and loss is computed using these prices.
  </Card>

  <Card title="Oracle Safeguards" icon="shield-halved" href="/protocol/oracle-safeguards">
    Defense-in-depth oracle protection details.
  </Card>

  <Card title="Publisher Operations" icon="tower-broadcast" href="/deploy/publisher-operations">
    Technical details of the publisher service for operators.
  </Card>
</Columns>