createOracle

The createOracle method is designed to facilitate the creation of an oracle, which serves as a reliable source of real-time data from a specified Application Programming Interface (API). This method is particularly suited for scenarios where only a single data point is required from the API.

Usage

As an example, we will utilize the CoinGecko public API, which provides the Ethereum price in USD: CoinGecko Ethereum API.

// create an observable
const createOracleObservable = factory.createOracle({
  url: 'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd',
  method: 'GET',
  headers: {
    authorization: '%API_KEY%',
  },
  dataType: 'number',
  JSONPath: '$.ethereum.usd',
  apiKey: 'MY_TEST_API_KEY',
});

// subscribe to the observable and start the workflow
createOracleObservable.subscribe({
  next: (data) => {
    console.log('next', data);
  },
  error: (error) => {
    console.log('error', error);
  },
  complete: () => {
    console.log('Oracle Creation Completed');
  },
});

Parameters

import { type RawParams } from '@iexec/iexec-oracle-factory-wrapper';

url Required *

string

The API URL to fetch data from.

const createOracleObservable = factory.createOracle({
  url: 'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd',
  method: 'GET',
  headers: {
    authorization: '%API_KEY%',
  },
  dataType: 'number',
  JSONPath: '$.ethereum.usd',
  apiKey: 'MY_TEST_API_KEY',
});

method Required *

'GET' | 'POST' | 'PUT' | 'DELETE'

The HTTP method to use when making the API request (e.g., "GET").

const createOracleObservable = factory.createOracle({
  url: 'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd',
  method: 'GET',
  headers: {
    authorization: '%API_KEY%',
  },
  dataType: 'number',
  JSONPath: '$.ethereum.usd',
  apiKey: 'MY_TEST_API_KEY',
});

headers

Record<string, string> | undefined

Any headers required for the API request.

const createOracleObservable = factory.createOracle({
  url: 'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd',
  method: 'GET',
  headers: { 
    authorization: '%API_KEY%',
  },
  dataType: 'number',
  JSONPath: '$.ethereum.usd',
  apiKey: 'MY_TEST_API_KEY',
})

dataType Required *

DataType

The type of data to be returned (e.g., "number").

const createOracleObservable = factory.createOracle({
  url: 'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd',
  method: 'GET',
  headers: {
    authorization: '%API_KEY%',
  },
  dataType: 'number',
  JSONPath: '$.ethereum.usd',
  apiKey: 'MY_TEST_API_KEY',
});

JSONPath Required *

string

The JSON path to extract the data from the API response.

const createOracleObservable = factory.createOracle({
  url: 'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd',
  method: 'GET',
  headers: {
    authorization: '%API_KEY%',
  },
  dataType: 'number',
  JSONPath: '$.ethereum.usd',
  apiKey: 'MY_TEST_API_KEY',
});

apiKey

string | undefined

API key if required by the data source.

The apiKey is protected an injected when an oracle is updated. %API_KEY% is used as a placeholder for the apiKey value in oracle public parameters url and headers.

const createOracleObservable = factory.createOracle({
  url: 'https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd',
  method: 'GET',
  headers: {
    authorization: '%API_KEY%',
  },
  dataType: 'number',
  JSONPath: '$.ethereum.usd',
  apiKey: 'MY_TEST_API_KEY',
});

Return value

Observable<CreateOracleMessage>

import type {
  CreateOracleMessage, // any `data` the `next(data)` handler can receive

  // all `data` types
  ApiKeyEncryptionKeyCreatedMessage, // encryption key for `apiKey` value created
  ApiKeyEncryptedMessage, // `apiKey` value encrypted
  ApiKeyUploadedMessage, // `apiKey` encrypted value uploaded on IPFS
  ApiKeyDatasetDeployRequestMessage, // requests the user to sign the API key's dataset deployment tx
  ApiKeyDatasetDeploySuccessMessage, // API key's dataset deployed
  ApiKeyPushSecretRequestMessage, // requests the user to push the encryption key in the SMS
  ApiKeyPushSecretSuccessMessage, // encryption key pushed
  ApiKeySignOrderRequestMessage, // requests the user to sign the dataset order
  ApiKeySignOrderSuccessMessage, // dataset order signed
  ApiKeyPublishOrderRequestMessage, // requests the user to publish the dataset order
  ApiKeyPublishOrderSuccessMessage, // dataset order published
  ParamSetCreatedMessage, // ParamSet created from inputs
  OracleIDComputedMessage, // OracleId computed from ParamSet
  ParamSetUploadedMessage, // ParamSet uploaded on IPFS
} from '@iexec/iexec-oracle-factory-wrapper';

TIP

Nothing happens before subscribe() is called on the returned observable.

You can provide custom next, complete and error callback methods to subscribe

// method to call when the workflow goes to a new step
const nextCallback: ObservableNext<CreateOracleMessage> = (data) => {
  // your logic
};

// method to call when the workflow completes successfully
const completeCallback: ObservableComplete = () => {
  // your logic
};

// method to call when the workflow fails
const errorCallback: ObservableError = (error: Error) => {
  // your logic
};

createOracleObservable.subscribe({
  next: nextCallback,
  complete: completeCallback,
  error: errorCallback,
});