@acurast/oracle-service-sdk
v1.1.3
Published
The Acurast Oracle SDK is a TypeScript library that provides a simple interface to interact with the Acurast Oracle Service. It allows developers to fetch price data for various cryptocurrency pairs, with signatures from multiple oracles.
Downloads
16
Readme
Acurast Oracle SDK
The Acurast Oracle SDK is a TypeScript library that provides a simple interface to interact with the Acurast Oracle Service. It allows developers to fetch price data for various cryptocurrency pairs, with signatures from multiple oracles.
Features
- Fetch price data for multiple cryptocurrency pairs
- Verify price data across multiple oracles
- Check the health status of supported exchanges
- Support for different blockchain protocols (Substrate, EVM, WASM, Tezos)
Installation
To install the Acurast Oracle SDK, use yarn:
yarn add acurast-oracle-service-sdk
Usage
Initializing the SDK
First, import and initialize the AcurastOracleSDK:
import { AcurastOracleSDK } from "acurast-oracle-sdk"
const sdk = new AcurastOracleSDK({
timeout: 5000, // (optional) default 10 seconds
logging: true, // (optional) default false
errorThreshold: 0.333, // (optional) default 0.333
})
Fetching Price Data
To fetch price data for cryptocurrency pairs:
const fetchPricesParams = {
pairs: [
{ from: "BTC", to: "USDT" },
{ from: "ETH", to: "USDT" },
],
protocol: "EVM",
aggregation: "median",
}
try {
const priceData = await sdk.getPrices(fetchPricesParams, 2) // Require 2 verifications
console.log("Price data:", priceData)
} catch (error) {
console.error("Error fetching prices:", error)
}
Checking Exchange Health
To check the health status of supported exchanges:
try {
const exchanges = await sdk.getExchanges()
console.log("Available exchanges:", exchanges)
} catch (error) {
console.error("Error checking exchange health:", error)
}
Closing the Connection
When you're done using the SDK, close the connection:
await sdk.close()
Response Examples
getPrices Response
;[
{
priceData: {
from: "BTC",
to: "USDT",
decimals: 8,
price: 5000000000000,
timestamp: 1629300000000,
sources: [
{ exchangeId: "BNC", certificate: "cert1" },
{ exchangeId: "CBP", certificate: "cert2" },
],
requestHash: "0x1234567890abcdef",
},
packed: ["packed_data_1", "packed_data_2"],
signatures: ["signature1", "signature2"],
pubKeys: ["pubKey1", "pubKey2"],
},
{
priceData: {
from: "ETH",
to: "USDT",
decimals: 8,
price: 300000000000,
timestamp: 1629300000000,
sources: [
{ exchangeId: "BNC", certificate: "cert1" },
{ exchangeId: "CBP", certificate: "cert2" },
],
requestHash: "0x1234567890abcdef",
},
packed: ["packed_data_3", "packed_data_4"],
signatures: ["signature3", "signature4"],
pubKeys: ["pubKey1", "pubKey2"],
},
]
getExchanges Response
;["BNC", "CBP", "BFX", "KRK", "GEM"]
Description
AcurastOracleSDK
Constructor
constructor(options: AcurastOracleSDKOptions)
options.wssUrls
: (Optional) Array of WebSocket URLs to connect to the Acurast processors.options.oracles
: (Optional) Array of processor public keys. These have to be public keys of processors that are running the AcurastOracleService. By default it will use the public keys from the AcurastOracleService.options.timeout
: (Optional) Timeout in milliseconds for the requests. Default: 10 seconds.options.logging
: (Optional) Enable or disable logs. Default: false.options.errorThreshold
: (Optional) Value from 0 to 1 that determines the percentage of oracles that have to respond with the same error for it to be thrown by the sdk. Default: 0.333.
Methods
getPrices(params: FetchPricesParams, verifications: number = 0): Promise<GetPricesResult[]>
Fetches price data from the oracle network.
params
: The parameters for fetching prices. It includes:pairs
: Array of Pairs, Pairs to fetch prices for:from
: String, from symbol.to
: String, to symbol.decimals
: Number of decimals for the price.price
: (Optional) Price(s) to verify against the oracle price. (Provide a price per aggregatyion type requested)timestamp
: (Optional) Number, timestamp of the provided prices.
protocol
: Protocol to package and sign the price data for.exchanges
: (Optional) List of exchange IDs to use as sources on the oracles. Default: all available exchanges.minSources
: (Optional) Minimum number of sources required. Default: 3.tradeAgeLimit
: (Optional) Maximum age of trade data in seconds. Default: 5 minutes.aggregation
: (Optional) Types of price aggregation requested from the oracles. Default: mean.maxSourcesDeviation
: (Optional) Maximum allowed standard deviation between prices in the sources. Default: no limit.maxValidationDiff
: (Optional) Maximum allowed price difference for validation against client. Default: 0.05%.
verifications
: The number of verifications required. Default: 0.
getPrices Response
GetPricesResult[]
Each object contains the following properties:
priceData
:from
: String - From symbol.to
: String - To symbol.decimals
: Number of decimals for the price.price
: Number or Number[] - Aggregated price(s).timestamp
: Number - Timestamp of the price data in ms.sources
: Array of Objects - Map exchangeID to the certificate for sources used.exchangeId
: String - The unique identifier of the exchange.certificate
: String - The API certificate.
requestHash
: String - Hash of the original request parameters.
packed
: String[] - Price data in the packed format for the chosen protocol.signatures
: String[] - Oracle signatures.pubKeys
: String[] - Oracle public keys.
getExchanges(params?: CheckExchangeHealthParams, requiredResponses: number = 0): Promise<string[]>
Retrieves a list of available exchanges.
params
: (Optional) The parameters for checking exchange health. It includes:exchanges
: (Optional) List of exchange IDs to check. Default: all available exchanges.
requiredResponses
: (Optional) The number of required responses from the oracles. Default: 0.
close(): Promise<void>
Closes the WebSocket connection.
Exchange ID table
| Exchange ID | Exchange Name | | ----------- | ------------- | | BNU | Binance US | | BNC | Binance | | CBP | Coinbase | | BFX | Bitfinex | | KRK | Kraken | | BYB | Bybit | | GEM | Gemini | | KUC | Kucoin | | GIO | Gate IO | | CRY | Crypto.com | | HTX | HTX | | MEXC | MEXC | | WBIT | Whitebit | | OKX | OKX | | UPB | Upbit |
License
This project is licensed under the MIT License.