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

# Oracle Price Feed

> How Limora obtains and uses price data for trading

Limora uses decentralized oracle price feeds to determine accurate market prices for opening, closing, and liquidating positions. This page explains how the oracle system works.

***

## Overview

Unlike order-book based exchanges where prices are determined by matching bids and asks, Limora uses **oracle-based pricing**. This approach offers several advantages:

<CardGroup cols={2}>
  <Card title="No Slippage" icon="equals">
    Trades execute at the oracle price, regardless of position size.
  </Card>

  <Card title="Manipulation Resistant" icon="shield">
    Prices are aggregated from multiple sources, making manipulation difficult.
  </Card>

  <Card title="Consistent Execution" icon="check">
    All trades in a block get the same price, ensuring fairness.
  </Card>

  <Card title="Transparent" icon="eye">
    Oracle prices are on-chain and independently verifiable.
  </Card>
</CardGroup>

***

## Price Sources

Limora aggregates prices from multiple reputable sources:

* **Chainlink**: Industry-leading decentralized oracle network
* **Pyth Network**: High-frequency price feeds from major exchanges
* **Band Protocol**: Cross-chain oracle solution

The protocol uses a median price from these sources to mitigate the impact of any single source being manipulated or experiencing issues.

***

## Price Feed Architecture

```mermaid theme={null}
graph LR
    subgraph "Data Sources"
        E1[Binance]
        E2[Coinbase]
        E3[Kraken]
        E4[OKX]
    end

    subgraph "Oracle Networks"
        O1[Chainlink]
        O2[Pyth]
        O3[Band]
    end

    subgraph "Limora"
        A[Aggregator]
        TC[Trading Contract]
    end

    E1 & E2 & E3 & E4 --> O1 & O2 & O3
    O1 & O2 & O3 --> A
    A --> TC
```

***

## Supported Price Feeds

| Asset    | Symbol  | Update Frequency | Deviation Threshold |
| -------- | ------- | ---------------- | ------------------- |
| Bitcoin  | BTC/USD | 1 second         | 0.1%                |
| Ethereum | ETH/USD | 1 second         | 0.1%                |
| Solana   | SOL/USD | 1 second         | 0.25%               |
| Arbitrum | ARB/USD | 10 seconds       | 0.5%                |
| Optimism | OP/USD  | 10 seconds       | 0.5%                |

<Note>
  Price feeds are continuously updated. The table above shows typical parameters
  which may be adjusted based on market conditions.
</Note>

***

## Price Calculation

### Entry Price

When opening a position, the entry price is determined by:

1. Fetching the latest oracle price at transaction execution
2. Applying any applicable spread (typically 0%)
3. Recording the price in the position data

### Mark Price

The mark price used for P\&L calculation and liquidations:

```
Mark Price = Oracle Price
```

For most trading pairs, the mark price equals the oracle price directly. For some pairs, a time-weighted average price (TWAP) may be used to smooth volatility.

### Settlement Price

When closing a position, the settlement price is:

1. The oracle price at the time of the close transaction
2. Used to calculate final P\&L
3. Determines fund distribution between trader and matcher

***

## Staleness Protection

To protect against stale or outdated prices, the protocol implements staleness checks:

```solidity theme={null}
require(
    block.timestamp - priceTimestamp < MAX_PRICE_AGE,
    "Price feed is stale"
);
```

| Parameter       | Value      | Description               |
| --------------- | ---------- | ------------------------- |
| MAX\_PRICE\_AGE | 60 seconds | Maximum age of price data |
| HEARTBEAT       | 10 seconds | Expected update frequency |

If a price feed becomes stale:

1. New positions cannot be opened for that pair
2. Existing positions continue using the last valid price
3. Alerts are triggered for protocol operators

***

## Deviation Protection

The protocol monitors for unusual price deviations:

```solidity theme={null}
require(
    abs(newPrice - lastPrice) / lastPrice < MAX_DEVIATION,
    "Price deviation too large"
);
```

This prevents extreme price swings from triggering mass liquidations due to oracle errors.

***

## Price Updates and Gas

Oracle price updates are performed by dedicated keeper networks that:

* Monitor off-chain price sources
* Submit on-chain updates when thresholds are met
* Pay gas costs for update transactions

Users do not need to pay for oracle updates; these costs are covered by the protocol.

***

## Liquidation Pricing

Liquidations use a specific pricing mechanism to ensure fairness:

1. **Trigger Check**: Position checked against current oracle price
2. **Grace Period**: Brief window before execution (configurable)
3. **Execution Price**: Oracle price at liquidation transaction

This prevents front-running of liquidations and ensures traders have fair opportunity to add margin.

***

## Oracle Governance

Oracle configuration is managed through protocol governance:

* Adding new price feeds requires governance approval
* Changing deviation thresholds requires governance approval
* Emergency pauses can be triggered by the security council

***

## Monitoring and Transparency

### On-Chain Data

All oracle prices are recorded on-chain and can be verified:

```solidity theme={null}
// Query current price
function getPrice(address asset) external view returns (
    uint256 price,
    uint256 timestamp,
    uint8 decimals
);

// Query historical price
function getHistoricalPrice(address asset, uint256 timestamp)
    external view returns (uint256 price);
```

### Price Dashboard

Monitor current and historical prices at:

* On-chain: Contract read functions
* API: `/api/prices` endpoint
* UI: Price charts on the trading interface

***

## Limitations

### Known Limitations

1. **Update Latency**: Oracle prices may lag spot prices by 1-10 seconds
2. **Weekend Gaps**: Some assets may have reduced update frequency during low-volume periods
3. **Network Congestion**: Base network congestion may delay price updates

### Best Practices

* Use stop-loss orders to limit downside risk
* Avoid extremely high leverage during volatile periods
* Monitor positions actively during major market events

***

## Technical Integration

For developers integrating with Limora's oracle system:

```typescript theme={null}
import { LimoraOracle } from '@limora/sdk'

const oracle = new LimoraOracle({
  provider: ethersProvider,
  network: 'base-mainnet',
})

// Get current price
const btcPrice = await oracle.getPrice('BTC')
console.log(`BTC Price: $${btcPrice.toFixed(2)}`)

// Subscribe to price updates
oracle.subscribe('ETH', (price, timestamp) => {
  console.log(`ETH: $${price} at ${timestamp}`)
})
```

***

<CardGroup cols={2}>
  <Card title="Protocol Overview" icon="diagram-project" href="/protocol/overview">
    Learn more about the protocol architecture.
  </Card>

  <Card title="API Reference" icon="book" href="/api/reference">
    Access price data via API.
  </Card>
</CardGroup>