# 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-1)

**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-1)

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 %}