Oracle Aggregator

Switchboard can fetch data from a number of oracles. Here's how to use them.

Pyth

The Pyth Oracle Network publishes price feeds that the Oracle Aggregator task can read through Hermes or from an on-chain Solana push-feed account. The two paths have different authentication and freshness behavior.

Hermes-backed feeds with pythAddress

Use pythAddress for the Hermes-backed path. It accepts existing Pyth Solana price account addresses and Pyth price-feed IDs. For authenticated Hermes access, place an API-key placeholder in pythConfigs.apiKey:

// SNX/USD with a 1.2% maximum confidence interval
{
  oracleTask: {
    pythAddress: "0x39d020f60982ed892abbcd4a06a276a9f9b7bfbce003204c110b6e488f502da3",
    pythConfigs: {
      apiKey: "${PYTH_API_KEY}",
      pythAllowedConfidenceInterval: 1.2,
      maxStaleSeconds: 15,
    },
  },
}

Provide the key on the same execution request:

const response = await gateway.fetchSignaturesConsensus({
  // ...feed request fields
  variableOverrides: {
    PYTH_API_KEY: process.env.PYTH_API_KEY!,
  },
});

For new feed definitions, prefer an explicit pythConfigs.apiKey placeholder. It makes the task's credential dependency visible and allows different Pyth tasks in one request to name different keys. After placeholder expansion, a non-empty task-level apiKey takes precedence.

Existing pythAddress jobs do not need to be rewritten during the Pyth Core transition. When pythConfigs.apiKey is omitted or empty, the task accepts the reserved request override PYTH_API_KEY as a compatibility fallback. One fallback value covers every pythAddress task in that execution request that does not set its own apiKey; it does not apply to other requests or become an oracle-wide key. This preserves existing feed definitions while allowing the customer making the request to pay for its Hermes calls.

The compatibility fallback assumes one execution request belongs to one customer or security domain. Do not combine unrelated customers' jobs and credentials in a single request.

On-chain push feeds with pythPushFeedId

Use pythPushFeedId for an upgraded Solana push feed. This path derives and reads the on-chain price account; it does not call Hermes and does not use a Hermes API key.

When authoring, storing, hashing, or updating a feed that uses this task, use @switchboard-xyz/common@5.8.5 and @switchboard-xyz/on-demand@3.10.6 or newer. The current Common serializer preserves the Pyth-push fields and explicitly set optional defaults in the canonical feed identity.

{
  oracleTask: {
    pythPushFeedId: "0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d",
    pythConfigs: {
      pushFeedShardId: 0,
      maxStaleSeconds: 75,
    },
  },
}

pushFeedShardId defaults to 0. maxStaleSeconds defaults to 15 for pythAddress and 75 for pythPushFeedId. pythConfigs.hermesUrl can select a different Hermes endpoint for pythAddress. Use the nested pythConfigs.pythAllowedConfidenceInterval field for confidence limits; values are percentages, so 10 means 10%. The top-level pythAllowedConfidenceInterval field is retained only for compatibility.

See Data Feed Variable Overrides for the request trust model, Jupiter API keys for its conventional placeholder behavior, and the OracleTask reference for every field.

Chainlink

The Chainlink Oracle Network provides 145 data feeds at the time of writing on the Arbitrum L2 Mainnet. Check out the available feed addresses here.

// AAVE/USD Task with accepted confidence interval of 1.2%
{
    oracleTask: {
        chainlinkAddress: "0x3c6AbdA21358c15601A3175D8dd66D0c572cc904"
    },
}

Switchboard V2

Switchboard V2 (Solana Push) feeds can be referenced within on-demand feeds. It's simple, all you need is an Aggregator public key, which you can find on the V2 Explorer App.

Here's an example of a Switchboard Oracle Task for the price of BTC/USD:

// BTC/USD Task
{
    oracleTask: {
        switchboardAddress: "8SXvChNYFhRq4EZuZvnhjrB3jJRQCv4k3P4W6hesH3Ee",
    }
}