🧙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: oracle.ln.exchange:443 REST: https://oracle.ln.exchange

---

Fetching Prices

GRPC Calls

Setup: Add the following configuration to your terminal --taproot-assets.experimental.rfq.priceoracleaddress=rfqrpc://oracle.ln.exchange:443

REST Calls

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

---

Adding Currency Pairs & Prices

Add Currency Pair & Price

There are 2 methods for adding assets/currency pairs:

Method 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.

Method 2: Manual Price Specification

This method is useful for testing purposes. You can manually specify the price of the assets.

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.

• Prices can be added multiple times; the system will always use the most recently added price when fetching.

• Note: For dynamic BTC-USDT pricing, set price=0 when adding the price. This value is fixed, and subsequent modifications are restricted.

Please refer to the API section for more details.

---

Price Oracle API

Quick Start

Example:

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

oracle ~ % grpcurl -d '{"subjectAsset":{"assetIdStr":"1f0e5e108dbaca43b836c8f0990abb5118bbe52c24b9237414d14cd53b1ad049"},"paymentAsset":{"assetIdStr":"0000000000000000000000000000000000000000000000000000000000000000"}}' oracle.ln.exchange:443 priceoraclerpc.PriceOracle.QueryRateTick
{
  "success": {
    "rate_tick": {
      "rate": "9000",
      "expiry_timestamp": "1724149789477"
    }
  }
}

---

GRPC Section

Fetch Price

• URL：oracle.ln.exchange:443

• Method：priceoraclerpc.PriceOracle.QueryRateTick

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)

Request Example

grpcurl -d '{"subjectAsset":{"assetIdStr":"1f0e5e108dbaca43b836c8f0990abb5118bbe52c24b9237414d14cd53b1ad049"},"paymentAsset":{"assetIdStr":"0000000000000000000000000000000000000000000000000000000000000000"}}' oracle.ln.exchange:443 priceoraclerpc.PriceOracle.QueryRateTick

Response Parameters

Parameter Name	Type	Description
rate_tick
rate	String	Price rate
expiry_timestamp	String	Expiry Timestamp

Response Example

{
  "success": {
    "rate_tick": {
      "rate": "9000",
      "expiry_timestamp": "1724144023331"
    }
  }
}

---

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：/napi/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)

Request Example

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

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

Response Example

{
    "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
}

---

Add Currency Pair & Price

• URL：/napi/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)
price	String	Yes	Price (Note: setting price = 0 will fetch real-time BTC-USDT price)
priceFluctuationRate	String	Yes	Price fluctuation rate: Default is 2%

Request Example (Price not equal to 0)

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

Request Example (Price equal to 0)

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

Response Parameters

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

Response Example

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