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

# Price Oracles

[Price Oracles](https://xrpl.org/docs/concepts/decentralized-storage/price-oracles) on the XRP Ledger bring real-world pricing data on-chain—bridging external market data with decentralized applications (dApps). This feature enables dApps, decentralized exchanges, and DeFi protocols to function with up-to-date, verifiable price feeds.

***

### Price Oracles Explained

#### What Are Price Oracles?

Price Oracles are on-chain ledger objects that store external price information (e.g., XRP/USD). They are created and updated via the **OracleSet** transaction, and can be removed using the **OracleDelete** transaction. dApps can access this data to trigger smart contract logic, perform asset conversions, or maintain stablecoins.

#### Why Use Price Oracles?

* **Reliable Data Feeds**: Provide verified, real-time pricing data from trusted providers.
* **Decentralized Trust**: Price data is recorded on the immutable XRPL ledger.
* **Data Aggregation**: Multiple oracle instances can be aggregated to calculate mean, median, or trimmed mean values, reducing the impact of outliers.

#### How Price Oracles Work

The PriceOracle object includes fields such as `Owner`, `Provider`, `PriceDataSeries`, and `LastUpdateTime`. You use an **OracleSet** transaction to create or update an oracle instance, while the **OracleDelete** transaction removes it from the ledger. Additionally, the `get_aggregate_price` API allows for combining data from multiple Price Oracle objects to generate reliable price statistics.

***

### Advantages of Price Oracles

1. **Real-World Data Integration**\
   Seamlessly integrate external pricing data into on-chain applications.
2. **Enhanced Transparency and Security**\
   Data stored on XRPL is verifiable and tamper-resistant.
3. **Robust Data Aggregation**\
   Aggregating data from several oracles minimizes anomalies and improves reliability.
4. **Dynamic Data Management**\
   Easily update or remove price feeds with dedicated transactions.

***

## Price Oracles in Action

### Prerequisites

Before working with Price Oracles, ensure you have:

* An active **Owner** account on the XRPL that meets the XRP reserve requirements.
* Sufficient XRP to cover transaction fees.
* Trust in your external data provider (e.g., a reputable API or on-chain oracle service).

#### Initialize the Client and Wallet

Begin by installing the XRPL library:

```bash
npm install xrpl
```

Then, initialize your XRPL client and wallet:

```javascript
import { Client, Wallet } from "xrpl";

const client = new Client("wss://xrplcluster.com");
await client.connect();

// Initialize your owner wallet (replace with your actual secret)
const ownerWallet = Wallet.fromSeed("sXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
```

### Example: Creating/Updating a Price Oracle

Submit an **OracleSet** transaction to create or update a Price Oracle instance:

```javascript
const oracleSetTx = {
    TransactionType: "OracleSet",
    Account: ownerWallet.classicAddress,
    OracleDocumentID: 34,  // Unique identifier for this Price Oracle instance
    Provider: "70726F7669646572", // Hex-encoded provider identifier (e.g., "provider")
    AssetClass: "63757272656E6379", // Hex-encoded asset class (e.g., "currency")
    LastUpdateTime: Math.floor(Date.now() / 1000), // Current Unix time
    PriceDataSeries: [
        {
            PriceData: {
                BaseAsset: "XRP",
                QuoteAsset: "USD",
                AssetPrice: 740,  // Example: represents 7.40 with a Scale of 2
                Scale: 2
            }
        }
    ]
};

try {
    const response = await client.submitAndWait(oracleSetTx, { autofill: true, wallet: ownerWallet });
    console.log("OracleSet Transaction Result:", response);
} catch (error) {
    console.error("Failed to submit OracleSet transaction:", error);
}
```

### Retrieving a Price Oracle

Use the `ledger_entry` API to fetch the on-chain Price Oracle object:

```javascript
const ledgerEntryRequest = {
    method: "ledger_entry",
    oracle: {
        account: ownerWallet.classicAddress,
        oracle_document_id: 34
    },
    ledger_index: "validated"
};

const ledgerEntryResponse = await client.request(ledgerEntryRequest);
console.log("Retrieved Price Oracle:", ledgerEntryResponse.result.node);
```

#### Convert AssetPrice to Integer

To get a decimal representation of the AssetPrice convert it from HEX to a Number:

```javascript
const AssetPriceHex = '0x' + '2e4'
const price = Number(AssetPriceHex)
```

### Aggregating Price Data

Aggregate data from multiple oracles with the `get_aggregate_price` API:

```javascript
const aggregatePriceRequest = {
    method: "get_aggregate_price",
    ledger_index: "current",
    base_asset: "XRP",
    quote_asset: "USD",
    trim: 20, // Trim 20% of outlier data
    oracles: [
        {
            account: ownerWallet.classicAddress,
            oracle_document_id: 34
        }
        // Include additional oracle objects as needed
    ]
};

const aggregatePriceResponse = await client.request(aggregatePriceRequest);
console.log("Aggregated Price Data:", aggregatePriceResponse.result);
```

### Additionally Delete the Oracle Object

To delete the Oracle Object from your Account perform an `OracleDelete` Transaction.

```javascript
const oracleDeleteTx = {
  TransactionType: "OracleDelete",
  Account: ownerWallet.classicAddress,
  OracleDocumentID: 34
};

try {
    const response = await client.submitAndWait(oracleDeleteTx, { autofill: true, wallet: ownerWallet });
    console.log("OracleDelete Transaction Result:", response);
} catch (error) {
    console.error("Failed to submit OracleDelete transaction:", error);
}
```

***

## Key Considerations

#### XRP Reserve Requirements

* Ensure your account meets the reserve requirement, especially when including more than five token pairs in `PriceDataSeries`.

#### Data Accuracy and Validity

* Validate that the `LastUpdateTime` reflects current pricing data.
* Maintain consistency for the `Provider` and `AssetClass` fields across updates.

#### Transaction Signing

* All OracleSet and OracleDelete transactions must be signed by the owner account or its authorized multi-signers.

***

## Advantages in Financial Applications

Price Oracles empower the XRPL ecosystem by enabling:

1. **Decentralized Finance (DeFi)**\
   Utilize real-world price data to support lending, derivatives, and other DeFi products.
2. **Stablecoin Management**\
   Maintain stablecoin peg values with aggregated price feeds.
3. **Efficient Trading and DEX Integration**\
   Provide reliable market data for order matching and automated market making.

By integrating Price Oracles, developers can build robust, data-driven applications that benefit from transparent and up-to-date market insights.

***

Remember to disconnect your client after operations:

```javascript
await client.disconnect();
```

Happy building with Price Oracles on XRPL!