# Price Oracle

## Overview

The LN Exchange Price Oracle is the cornerstone of decentralized finance within the Lightning Network, primarily serving RFQ (Request for Quote) services. This platform provides dynamic pricing, including price fluctuations and a spread between buy and sell prices, ensuring accurate and reliable rates for assets traded on the network.

This guide will walk you through integrating with the platform, fetching prices, and adding currency pairs.

***

## Unified Interface Domain

**GRPC:** `grpc-oracle.lnfi.network:443`\
**REST:** `https://api-oracle.lnfi.network`

***

## Fetching Prices

#### **GRPC Calls**

{% code overflow="wrap" %}

```
Setup: Add the following configuration to your terminal --taproot-assets.experimental.rfq.priceoracleaddress=rfqrpc://grpc-oracle.lnfi.network:443
```

{% endcode %}

#### **REST Calls**

{% code overflow="wrap" %}

```
REST API documentation in the section below provides details on how to integrate.
```

{% endcode %}

***

## Adding Currency Pairs & Prices

### [Add Currency Pair](#add-currency-pair-and-price)

**Using BTC/USDT Price**

This method is intended for assets that are tied to the USDT stablecoin. When this method is used, the system automatically fetches the current BTC/USDT price, ensuring that your asset's value reflects real-time market conditions.

### [Fetch Price](#fetch-price)

After adding prices using either method, prices can be fetched immediately.

* If a currency pair or currency doesn’t exist, the system will automatically create them.
* Each asset can only be added once. When fetching prices, the system always uses the latest price.

Please refer to the API section for more details.

***

## Price Oracle API

### Quick Start

{% code title="Example:" lineNumbers="true" %}

```
oracle ~ % curl --location --request POST 'https://api-oracle.lnfi.network/price/custom' \
--header 'Content-Type: application/json' \
--data-raw '{
    "paymentAssetName": "BTC",
    "paymentAssetId": "0000000000000000000000000000000000000000000000000000000000000000",
    "subjectAssetName": "LUSDT",
    "subjectAssetId": "1f0e5e108dbaca43b836c8f0990abb5118bbe52c24b9237414d14cd53b1ad049",
    "subjectAssetDemical": "2",
    "priceFluctuationRate": "0.02"
}'
{"code":"0","msg":"Success","data":true,"succ":true}

oracle ~ % grpcurl -d '{"subjectAsset":{"assetIdStr":"1f0e5e108dbaca43b836c8f0990abb5118bbe52c24b9237414d14cd53b1ad049"},"paymentAsset":{"assetIdStr":"0000000000000000000000000000000000000000000000000000000000000000"}}' grpc-oracle.lnfi.network:443 priceoraclerpc.PriceOracle.QueryAssetRates
{
  "ok": {
    "asset_rates": {
      "subjectAssetRate": {
        "coefficient": "8733623000000",
        "scale": 6
      },
      "paymentAssetRate": {
        "coefficient": "100000000000"
      },
      "expiry_timestamp": "1766549104533"
    }
  }
}
```

{% endcode %}

***

## GRPC Section

### Fetch Price

* **URL**：`grpc-oracle.lnfi.network:443`
* **Method**：`priceoraclerpc.PriceOracle.QueryAssetRates`

**Request Parameters**

| Parameter Name          | Type   | Required | Description                           |
| ----------------------- | ------ | -------- | ------------------------------------- |
| subjectAsset.assetidStr | String | Yes      | Quoted currency asset ID (e.g., USDT) |
| subjectAsset.assetidStr | String | Yes      | Base currency asset ID (e.g., BTC)    |

{% hint style="info" %}
\*\*Request Example\*\*
{% endhint %}

```
grpcurl -d '{
    "paymentAsset": {
        "assetIdStr": "0000000000000000000000000000000000000000000000000000000000000000"
    },
    "subjectAsset": {
        "assetIdStr": "1f0e5e108dbaca43b836c8f0990abb5118bbe52c24b9237414d14cd53b1ad049"
    }
}' grpc-oracle.lnfi.network:443 priceoraclerpc.PriceOracle.QueryAssetRates
```

**Response Parameters**

| Parameter Name                | Type   | Description      |
| ----------------------------- | ------ | ---------------- |
| asset\_rates.subjectAssetRate |        |                  |
| rate                          | String | Price rate       |
| expiry\_timestamp             | String | Expiry Timestamp |

{% hint style="info" %}
**Response Example**
{% endhint %}

```
{
  "ok": {
    "asset_rates": {
      "subjectAssetRate": {
        "coefficient": "8733623000000",
        "scale": 6
      },
      "paymentAssetRate": {
        "coefficient": "100000000000"
      },
      "expiry_timestamp": "1766549104533"
    }
  }
}
```

***

## REST Section API

### REST Request Authentication

All private REST requests must include the following header

#### Header Parameters

| Parameter Name | Type   | Required | Value            |
| -------------- | ------ | -------- | ---------------- |
| Content-Type:  | String | Yes      | application/json |

***

### Fetch Price List

* **URL**：`/price/getList`
* **Method**：`GET`

**Request Parameters**

| Parameter Name    | Type   | Required | Value                                    |
| ----------------- | ------ | -------- | ---------------------------------------- |
| symbolAssetsId    | String | Yes      | Currency pair asset ID                   |
| transaction\_type | String | Yes      | Transaction type: 0 = buy, 1 = sell      |
| current           | String | No       | Page number (default is 1)               |
| size              | String | No       | Number of items per page (default is 10) |

{% hint style="info" %}
\*\*Request Example\*\*
{% endhint %}

{% code lineNumbers="true" %}

```
{
    "symbolAssetsId": "0000000000000000000000000000000000000000000000000000000000000000-1f0e5e108dbaca43b836c8f0990abb5118bbe52c24b9237414d14cd53b1ad049",
    "transaction_type": "1",
    "current": "1",
    "size": "10"
}
```

{% endcode %}

**Response Parameters**

| Parameter Name    | Type   | Description                         |
| ----------------- | ------ | ----------------------------------- |
| total             | String | Total number of records             |
| pages             | String | Total number of pages               |
| transaction\_type | String | Transaction type: 0 = buy, 1 = sell |
|                   |        |                                     |
| list              | List   |                                     |
| symbol            | String | Currency pair name                  |
| price             | String | Price                               |
| base              | String | Base currency name (e.g, BTC)       |
| baseAssetsId      | String | Base currency asset ID              |
| quote             | String | Quoted currency name (e.g, USDT)    |
| quoteAssetsId     | String | Quoted currency asset ID            |
| ctime             | String | Creation time                       |

{% hint style="info" %}
**Response Example**
{% endhint %}

{% code lineNumbers="true" %}

```
{
    "code": "0",
    "msg": "Success",
    "data": {
        "total": 1,
        "pages": 1,
        "list": [
            {
                "symbol": "BTC-LUSDT",
                "price": 10000,
                "ctime": "2024-08-19T10:01:03",
                "base": "BTC",
                "baseAssetsId": "0000000000000000000000000000000000000000000000000000000000000000",
                "quote": "LUSDT",
                "quoteAssetsId": "1f0e5e108dbaca43b836c8f0990abb5118bbe52c24b9237414d14cd53b1ad049"
            }
        ],
        "transaction_type": "1"
    },
    "succ": true
}
```

{% endcode %}

***

### Add Currency Pair

* **URL**：`/price/custom`
* **Method**：`POST`

**Request Parameters**

| Parameter Name       | Type   | Required | Description                               |
| -------------------- | ------ | -------- | ----------------------------------------- |
| paymentAssetName     | String | Yes      | Base currency name (e.g., BTC)            |
| paymentAssetId       | String | Yes      | Base currency asset ID                    |
| subjectAssetName     | String | Yes      | Quoted currency name (e.g., USDT)         |
| subjectAssetId       | String | Yes      | Quoted currency asset ID                  |
| subjectAssetDemical  | String | Yes      | Quoted currency asset precision (e.g., 4) |
| priceFluctuationRate | String | Yes      | Price fluctuation rate: Default is 2%     |

{% hint style="info" %}
**Request Example**
{% endhint %}

{% code lineNumbers="true" %}

```
{
    "paymentAssetName": "BTC",
    "paymentAssetId": "0000000000000000000000000000000000000000000000000000000000000000",
    "subjectAssetName": "LUSDT",
    "subjectAssetId": "1f0e5e108dbaca43b836c8f0990abb5118bbe52c24b9237414d14cd53b1ad049",
    "subjectAssetDemical": "4",  
    "priceFluctuationRate": "0.02"
}
```

{% endcode %}

**Response Parameters**

| Parameter Name | Type   | Description                        |
| -------------- | ------ | ---------------------------------- |
| code           | String | 0 indicates successful addition    |
| data           | String | true indicates successful addition |

{% hint style="info" %}
**Response Example**
{% endhint %}

{% code lineNumbers="true" %}

```
{
    "code": "0",
    "msg": "Success",
    "data": true,
    "succ": true
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ln.exchange/price-oracle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.