@acurast/oracle-service-sdk v1.1.3

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:

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

2. packed: String[] - Price data in the packed format for the chosen protocol.

3. signatures: String[] - Oracle signatures.

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

License

This project is licensed under the MIT License.