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

# Oracle Infrastructure

> How Ratio sources and validates real-time FX rates for pricing

Ratio's pricing is anchored to real-world FX rates from institutional-grade oracle feeds. The oracle infrastructure is designed for reliability, accuracy, and redundancy — ensuring every quote reflects current market conditions.

## Oracle architecture

<img src="https://mintcdn.com/ratiolabs/_WZ1jJo-JiN7xW7b/images/oracle-infrastructure.svg?fit=max&auto=format&n=_WZ1jJo-JiN7xW7b&q=85&s=1dd87ffbeb74f276fe12c796352ddc53" alt="Oracle Infrastructure" width="680" height="180" data-path="images/oracle-infrastructure.svg" />

The system follows a layered approach:

<Steps>
  <Step title="External price sources">
    Raw FX rate data from Pyth Network (primary) and Web2 FX APIs (fallback).
  </Step>

  <Step title="Oracle Keeper service">
    Fetches prices from external sources and pushes them to the on-chain Oracle Aggregator contract.
  </Step>

  <Step title="Oracle Aggregator contract">
    Validates, aggregates, and stores the latest prices on-chain. Single source of truth.
  </Step>

  <Step title="FX Engine reads prices">
    The pricing pipeline reads aggregated prices from the on-chain contract when constructing quotes.
  </Step>
</Steps>

<Note>
  The FX Engine never reads oracle prices directly from external sources. All prices flow through the on-chain aggregator, ensuring a single source of truth with full auditability.
</Note>

## Pyth Network (primary source)

[Pyth Network](https://pyth.network) is Ratio's primary oracle. Key characteristics:

| Property              | Value                                            |
| --------------------- | ------------------------------------------------ |
| Update frequency      | \~400 milliseconds                               |
| Coverage              | 380+ price feeds including FX pairs              |
| Data quality          | Each price includes a confidence interval        |
| Data sources          | Professional market makers and trading firms     |
| On-chain availability | Available on Kaia via Pyth contract + Hermes API |

Ratio uses Pyth feeds for all Phase 1 corridors: USD/IDR, USD/SGD, and USD/MYR. For MYR/IDR, where a direct Pyth feed may not be available, the rate is derived from USD/IDR and USD/MYR — using USD purely as a pricing reference.

## Web2 FX API (fallback source)

For redundancy, Ratio integrates traditional Web2 FX data providers as fallback sources. These are used when the primary oracle is unavailable or when an independent reference is needed for validation.

The Web2 adapter is pluggable — the system can switch between providers without changing core logic.

## Price validation

Every oracle price is validated before use:

| Check                  | What it verifies                                                        | Failure response                                                |
| ---------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Freshness**          | Is the price recent enough? Each corridor has a maximum acceptable age. | Approaching staleness → wider spreads. Stale → circuit breaker. |
| **Source consistency** | Do multiple sources agree?                                              | Minor divergence → caution mode. Major divergence → halt.       |
| **Reasonableness**     | Does the price fall within expected bounds?                             | Out of bounds → halt and alert.                                 |

<Warning>
  Validation runs on every single quote request — there is no cached or assumed pricing. If reliable data is unavailable, the system halts rather than quoting at an unreliable price.
</Warning>

## Cross-currency rate construction

For pairs without a direct oracle feed (e.g., MYR/IDR), the system constructs a reference rate:

```
MYR/IDR rate = USD/IDR rate ÷ USD/MYR rate
```

This is standard cross-rate construction used universally in institutional FX. USD is used only as a mathematical reference — no actual USD conversion occurs. The swap executes directly between MYRC and IDRX.

When a direct oracle feed becomes available for a cross-currency pair, the system automatically prefers the direct feed and uses the synthetic rate only for arbitrage validation.

## Reliability design

<CardGroup cols={2}>
  <Card title="Multiple sources" icon="layer-group">
    Independent oracle providers prevent single-point-of-failure dependency.
  </Card>

  <Card title="On-chain aggregation" icon="link">
    Oracle data is immutably recorded and auditable on Kaia.
  </Card>

  <Card title="Automatic failover" icon="rotate">
    Switches between sources based on freshness and reliability.
  </Card>

  <Card title="Circuit breakers" icon="shield-halved">
    Halts trading rather than executing at unreliable prices.
  </Card>
</CardGroup>