Switchboard

https://docs.switchboard.xyz
Admin
Switchboard is a permissionless, decentralized oracle protocol delivering real-time on-chain data...
Tokens:246,022
Snippets:1,789
Trust Score:8.8
Update:6 days ago
Show doc for...
Tokens:
Raw
### Quick Start: Clone, Install, and Build Price Feeds

Source: https://docs.switchboard.xyz/docs-by-chain/evm/monad

Clones the sb-on-demand-examples repository, installs dependencies, installs forge-std for the coin-flip example, builds the project, and copies the .env.example file.

```bash
git clone https://github.com/switchboard-xyz/sb-on-demand-examples.git
cd sb-on-demand-examples/evm/price-feeds
bun install
(
  cd ../randomness/coin-flip
  [ -d lib/forge-std ] || forge install foundry-rs/forge-std --no-git --shallow
)
forge build
cp .env.example .env

```

--------------------------------

### Clone and install the examples repository

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/x402/x402-tutorial

Clones the sb-on-demand-examples repository and installs dependencies for the Solana x402 example using pnpm.

```bash
git clone https://github.com/switchboard-xyz/sb-on-demand-examples.git
cd sb-on-demand-examples/solana/x402
pnpm install
```

--------------------------------

### Run the example with pnpm start

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/x402/x402-tutorial

Starts the example application. The expected output shows the wallet address, RPC method, USDC balance, X402 client initialization, payment signature generation, feed ID, quote account, instruction generation, transaction building, simulation, and success message.

```bash
pnpm start
```

--------------------------------

### Install Dependencies

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/price-feeds/advanced-price-feed

Installs the npm dependencies required for the example.

```bash
npm install
```

--------------------------------

### Setup Coin Flip project

Source: https://docs.switchboard.xyz/docs-by-chain/evm/monad

Commands to install dependencies, install forge-std, build the project, and copy the environment file.

```bash
cd ../randomness/coin-flip
bun install
[ -d lib/forge-std ] || forge install foundry-rs/forge-std --no-git --shallow
forge build
cp .env.example .env
```

--------------------------------

### Expected output from running the example

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/x402/x402-tutorial

Shows the expected console output when running the example with pnpm start. It includes placeholders like <your-wallet-address>, <feed-hash>, and <quote-account-address>, and confirms simulation succeeded.

```text
Wallet: <your-wallet-address>
RPC Method: getBlockHeight
USDC balance: 10.500000 USDC
X402 v2 client initialized

Deriving X402 PAYMENT-SIGNATURE...
X402 PAYMENT-SIGNATURE generated
Feed ID: 0x<feed-hash>
Quote Account: <quote-account-address>

Fetching managed update instructions with X402 variable overrides...
Generated instructions: 2
   - Ed25519 signature verification
   - Quote program verified_update
   - Variable overrides: X402_PAYMENT_SIGNATURE

Building transaction...
Simulating transaction...
<transaction logs>

Simulation succeeded!
```

--------------------------------

### Setup: Load environment and get default queue

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/randomness/randomness-tutorial

Imports required libraries and loads the environment, default queue, and program instances. This is the initial setup for using Switchboard on-demand randomness.

```typescript
import * as anchor from "@coral-xyz/anchor";
import { Keypair, PublicKey, SystemProgram } from "@solana/web3.js";
import * as sb from "@switchboard-xyz/on-demand";

async function main() {
  // Load environment
  const { keypair, connection, program } = await sb.AnchorUtils.loadEnv();

  // Get the default Switchboard queue
  const queue = await sb.getDefaultQueue(connection.rpcEndpoint);

  // Load your program
  const myProgram = await loadMyProgram(program.provider);
  const sbProgram = await loadSbProgram(program.provider);
}
```

--------------------------------

### Run the example (bun run example)

Source: https://docs.switchboard.xyz/docs-by-chain/evm/price-feeds/price-feeds-tutorial

Runs the example. If CONTRACT_ADDRESS is unset, a fresh consumer contract is deployed before fetching the v2 update and submitting it on-chain.

```bash
bun run example
```

--------------------------------

### Install Kubernetes with k3s

Source: https://docs.switchboard.xyz/how-it-works/switchboard-protocol/running-a-switchboard-oracle/installation-setup-via-scripts/bare-metal-with-kubernetes-k3s-%2B-amd-sev-snp

Run the k3s installation script to download, install, and start k3s. After it settles, you can check with k9s or kubectl.

```bash
./30-k3s-install.sh
```

--------------------------------

### Clone and Install Dependencies

Source: https://docs.switchboard.xyz/docs-by-chain/evm/randomness/randomness-tutorial

Commands to clone the sb-on-demand-examples repository, install dependencies with bun or npm, install forge-std, and build the project.

```bash
git clone https://github.com/switchboard-xyz/sb-on-demand-examples
cd sb-on-demand-examples/evm/randomness/pancake-stacker
bun install  # or npm install
[ -d lib/forge-std ] || forge install foundry-rs/forge-std --no-git --shallow
forge build
```

--------------------------------

### Clone the Examples Repository

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/price-feeds/basic-price-feed

Clones the sb-on-demand-examples repository and navigates to the basic feed example directory.

```bash
git clone https://github.com/switchboard-xyz/sb-on-demand-examples
cd sb-on-demand-examples/solana/feeds/basic
```

--------------------------------

### Test TLS certificate setup

Source: https://docs.switchboard.xyz/how-it-works/switchboard-protocol/running-a-switchboard-oracle/installation-setup-via-scripts/bare-metal-with-kubernetes-k3s-%2B-amd-sev-snp

Run one of these commands to create an Ingress that tests the Kubernetes installation, DNS setup, and the entire flow. Choose the network that applies: devnet is the default, mainnet is for mainnet. Wait 3-5 minutes then visit the DNS record.

```bash
# only choose the one that applies to your setup - optional step
./80-test-cert-setup.sh # uses devnet by default
./80-test-cert-setup.sh devnet  # equivalent to above
./80-test-cert-setup.sh mainnet # run this for mainnet
```

--------------------------------

### Clone the examples repository

Source: https://docs.switchboard.xyz/docs-by-chain/sui/price-feeds/price-feeds-tutorial

Clones the Switchboard on-demand examples repository and navigates to the Sui feeds basic example directory.

```bash
git clone https://github.com/switchboard-xyz/sb-on-demand-examples
cd sb-on-demand-examples/sui/feeds/basic
```

--------------------------------

### Install Dependencies

Source: https://docs.switchboard.xyz/docs-by-chain/sui/surge/surge-tutorial

Install the required packages for Surge integration: @switchboard-xyz/on-demand, @switchboard-xyz/sui-sdk, @mysten/sui, and @solana/web3.js.

```bash
npm install @switchboard-xyz/on-demand@3.10.6 @switchboard-xyz/sui-sdk@0.1.16 @mysten/sui@1.38.0 @solana/web3.js@1.98.4
```

--------------------------------

### Clone the Examples Repository

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/price-feeds/advanced-price-feed

Clones the Switchboard on-demand examples repository and navigates to the advanced feeds example directory.

```bash
git clone https://github.com/switchboard-xyz/sb-on-demand-examples
cd sb-on-demand-examples/solana/feeds/advanced
```

--------------------------------

### Install helm and k9s utilities

Source: https://docs.switchboard.xyz/how-it-works/switchboard-protocol/running-a-switchboard-oracle/installation-setup-via-scripts/bare-metal-with-kubernetes-k3s-%2B-amd-sev-snp

Run the second installation script to install utility tools like helm and k9s for interacting with Kubernetes more efficiently.

```bash
./01-helm-install.sh
```

--------------------------------

### Monad example: curl GET /v2/update

Source: https://docs.switchboard.xyz/tooling/crossbar/api-endpoints

Example curl command for GET /v2/update with chain=evm, network=testnet, use_timestamp=true.

```bash
curl "http://localhost:8080/v2/update/0x4cd1cad962425681af07b9254b7d804de3ca3446fbfd1371bb258d2c75059812?chain=evm&network=testnet&use_timestamp=true"
```

--------------------------------

### Run the example with environment variables

Source: https://docs.switchboard.xyz/docs-by-chain/sui/price-feeds/price-feeds-tutorial

Sets the network and package ID environment variables, then runs the example. Optionally sets custom feed hash and number of oracles.

```bash
# Match the network to the Move package you deployed
export SUI_NETWORK=testnet
export EXAMPLE_PACKAGE_ID=0xYOUR_PACKAGE_ID

# Run the example
npm run example

# Or with custom parameters
export FEED_HASH=0x4cd1cad962425681af07b9254b7d804de3ca3446fbfd1371bb258d2c75059812
export NUM_ORACLES=5
npm run example
```

--------------------------------

### Run the Example

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/price-feeds/advanced-price-feed

Runs the example using the default BTC/USD feed or a custom feed ID via the --feedId flag.

```bash
# Using default BTC/USD feed
npm run update

# Using a custom feed ID
npm run update -- --feedId YOUR_FEED_ID
```

--------------------------------

### Deploy with packaged wrapper (bun run deploy)

Source: https://docs.switchboard.xyz/docs-by-chain/evm/price-feeds/price-feeds-tutorial

Use the packaged wrapper to deploy the example. Defaults to Monad testnet; use NETWORK=monad-mainnet to switch to mainnet. Requires PRIVATE_KEY.

```bash
# Default: Monad testnet
bun run deploy

# Explicit aliases
bun run deploy:monad-testnet
bun run deploy:monad-mainnet

# Flip to mainnet with one env var
NETWORK=monad-mainnet bun run deploy
```

--------------------------------

### ExponentTask example configuration

Source: https://docs.switchboard.xyz/custom-feeds/task-types

Example JSON configuration for the ExponentTask, which gets the exchange rate between an Exponent vault principal token and the underlying token. The input is the vault address.

```json
{
  "exponentTask": {
    "vault": "9YbaicMsXrtupkpD72pdWBfU6R7EJfSByw75sEpDM1uH"
  }
}
```

--------------------------------

### Clone the examples repository

Source: https://docs.switchboard.xyz/docs-by-chain/evm/price-feeds/price-feeds-tutorial

Clone the sb-on-demand-examples repository and navigate to the EVM price feeds example directory.

```bash
git clone https://github.com/switchboard-xyz/sb-on-demand-examples
cd sb-on-demand-examples/evm/price-feeds
```

--------------------------------

### GET /updates/evm/{chainId}/{aggregatorIds} legacy response

Source: https://docs.switchboard.xyz/ai-agents-llms/switchboard-agent-skill/switchboard-crossbar-ops

Example response from GET /updates/evm legacy route. Contains results array with result value, failures array, and encoded array.

```json
{
  "results": [
    {
      "result": "123450000000000000000"
    }
  ],
  "failures": [],
  "encoded": [
    "0x8f6f2b7c..."
  ]
}
```

--------------------------------

### Run the example on Monad mainnet

Source: https://docs.switchboard.xyz/docs-by-chain/evm/price-feeds/price-feeds-tutorial

Switch to Monad mainnet without changing the script by setting NETWORK=monad-mainnet.

```bash
NETWORK=monad-mainnet bun run example
```

--------------------------------

### Copy Environment Example File

Source: https://docs.switchboard.xyz/docs-by-chain/evm/randomness/randomness-tutorial

Copies the .env.example file to .env for configuration.

```bash
cp .env.example .env
```

--------------------------------

### GET /updates/sui/{network}/{aggregatorAddresses} - Example Response

Source: https://docs.switchboard.xyz/tooling/crossbar/api-endpoints

Example 200 response for the Sui updates endpoint. Contains 'responses' (per-aggregator update objects from Sui SDK fetchUpdateInfo) and 'failures' (top-level route errors).

```json
{
  "responses": [
    {
      "results": [],
      "failures": []
    }
  ],
  "failures": []
}
```

--------------------------------

### Run the Example Against the Preconfigured Devnet Program

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/randomness/randomness-tutorial

Runs the example with either 'heads' or 'tails' as the guess, using the preconfigured devnet program ID from Anchor.toml.

```bash
npm run start -- heads
# or
npm run start -- tails
```

--------------------------------

### ExponentPTLinearPricingTask example configuration

Source: https://docs.switchboard.xyz/custom-feeds/task-types

Example JSON configuration for the ExponentPTLinearPricingTask, which computes the current price of an Exponent principal token using a linear schedule from start_price to 1.0 at maturity. The input includes the vault address and starting price.

```json
{
  "exponentPtLinearPricingTask": {
    "vault": "9YbaicMsXrtupkpD72pdWBfU6R7EJfSByw75sEpDM1uH",
    "startPrice": 0.8
  }
}
```

--------------------------------

### Expected output of the example

Source: https://docs.switchboard.xyz/docs-by-chain/sui/price-feeds/price-feeds-tutorial

Shows the expected console output when running the example, including configuration, Switchboard connection, user address, steps, and the PriceUpdated event.

```text
Switchboard Oracle Quote Verifier Example

Configuration:
  Network: testnet
  Package: 0xYOUR_PACKAGE_ID
  Feed: 0x4cd1cad962425681af07b9254b7d804de3ca3446fbfd1371bb258d2c75059812
  Oracles: 3

Switchboard Connected:
  Oracle Queue: 0xe9324b82374f18d17de601ae5a19cd72e8c9f57f54661bf9e41a76f8948e80b5
  Network: Testnet

User Address: 0x...

Step 1: Creating QuoteConsumer...
QuoteConsumer Created: 0x...

Step 2: Fetching Oracle Data...
Oracle data fetched successfully

Step 3: Verifying and Updating Price...
Price Update Successful!

PriceUpdated Event:
  Feed Hash: 4cd1cad962425681af07b9254b7d804de3ca3446fbfd1371bb258d2c75059812
  New Price: 98765432100
  Timestamp: 2025-12-18T10:30:00.000Z
  Oracles: 3
```

--------------------------------

### GET /updates/aptos/{network}/{aggregatorAddresses} - Example Response

Source: https://docs.switchboard.xyz/tooling/crossbar/api-endpoints

Example 200 response for the Aptos updates endpoint. Contains 'responses' (per-aggregator update objects), 'failures' (top-level route errors), and 'encoded' (flattened list of encoded Aptos update payloads).

```json
{
  "responses": [
    {
      "responses": [],
      "failures": [],
      "encoded": [
        "0x..."
      ]
    }
  ],
  "failures": [],
  "encoded": [
    "0x..."
  ]
}
```

--------------------------------

### Generic HTTP API Task Configuration

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/prediction-market/prediction-market-tutorial

Shows how to configure a Switchboard Task for a generic HTTP GET request to an example API endpoint.

```rust
Task {
    task: Some(task::Task::HttpTask(HttpTask {
        url: Some("https://api.example.com/data".to_string()),
        method: Some(Method::Get as i32),
        ..Default::default()
    })),
}
```

--------------------------------

### GET /v2/update/{feedHashes}?chain=evm&network=testnet&use_timestamp=true response

Source: https://docs.switchboard.xyz/ai-agents-llms/switchboard-agent-skill/switchboard-crossbar-ops

Example response from GET /v2/update for EVM testnet. Contains medianResponses, oracleResponses, timestamp, slot, recentHash, and encoded. For EVM consumers, wrap encoded into a one-element bytes[] when calling getFee or updateFeeds.

```json
{
  "medianResponses": [
    {
      "value": "123450000000000000000",
      "feedHash": "0xfd2b067707a96e5b67a7500e56706a39193f956a02e9c0a744bf212b19c7246c",
      "numOracles": 3
    }
  ],
  "oracleResponses": [],
  "timestamp": 1730000000,
  "slot": 0,
  "recentHash": "0xabc123...",
  "encoded": "0x8f6f2b7c..."
}
```

--------------------------------

### Numbered script ordering example

Source: https://docs.switchboard.xyz/how-it-works/switchboard-protocol/running-a-switchboard-oracle/installation-setup-via-scripts

Illustrates how scripts are named with numerical prefixes to indicate the order they should be run, from 00-kernel-install.sh to 90-k8s-oracle-install.sh.

```bash
00-kernel-install.sh # absolutely FIRST step
# [...]
30-k3s-install.sh # then this needs to be run before ...
31-k3s-sail-setup.sh # ... this script but ...
# [...]
70-k8s-apps-cert-manager.sh # ... this happens even 
                            # later in the setup!
# [...]
90-k8s-oracle-install.sh # this is usually 
                         # the last step you'll run
```

--------------------------------

### Setup: Initialize Sui and Solana clients

Source: https://docs.switchboard.xyz/docs-by-chain/sui/surge/surge-tutorial

Initializes the SuiClient, SwitchboardClient, and Solana Connection. Use the Sui testnet URL for testnet.

```typescript
const suiClient = new SuiClient({ url: 'https://fullnode.mainnet.sui.io:443' });
const switchboardClient = new SwitchboardClient(suiClient);
const solanaConnection = new Connection('https://api.mainnet-beta.solana.com');
```

--------------------------------

### GET /updates/solana/{network}/{feedPubkeys} - Example Response

Source: https://docs.switchboard.xyz/tooling/crossbar/api-endpoints

Example 200 response for the Solana updates endpoint. Contains an array of update objects with 'success', 'pullIxns' (hex-encoded bincode serialized instructions), 'responses' (oracle responses), and 'lookupTables' (address lookup table pubkeys).

```json
[
  {
    "success": true,
    "pullIxns": [
      "0673bd46f2e47e04f12bd92fb731968ecd9d9757c274da87476f465c040c6573050000000000000089e0fecf1c1b3a11e77b9d1048192288ae1d8ada0e19ff95d737c4e5afb583f70001d284bd424eb258f1f502c95ff334245b64af7df6b14435d1ea46d10fb3ac68b6000086807068432f186a147cf0b13a30067d386204ea9d6c8b04743ac2ef010b075200007752c55e8b0a7079ad51975736764e45f56d61ebd15aa96d55f7ca86d5b5e387010100000000000000000000000000000000000000000000000000000000000000000000310000000000000001020304050607081d3c620d5670b1b26d0d3c7c27cb75a5187d99b8ccf8850d5b79d573b81bff7c030000009600000000"
    ],
    "responses": [
      {
        "oracle": "9pPCSotuPGUDgdYUtngMCemNi3KHdWFvwLhqx57KkbXb",
        "result": 1.1067679409326794,
        "errors": ""
      }
    ],
    "lookupTables": [
      "A43DyUGA7s8eXPxqEjJY6EBu1KKbNgfxF8h17VAHn13w"
    ]
  }
]
```

--------------------------------

### Backward-compatible API prefix

Source: https://docs.switchboard.xyz/tooling/crossbar/api-endpoints

Crossbar also exposes simulation routes under /api/simulate for compatibility. Examples include POST /api/simulate and GET /api/simulate/{feedHashes}.

```APIDOC
## Backward-compatible API prefix

### Description
Crossbar also exposes simulation routes under /api/simulate for compatibility. Examples include POST /api/simulate and GET /api/simulate/{feedHashes}.

### Endpoint
/api/simulate

```

--------------------------------

### Build Iota update payloads

Source: https://docs.switchboard.xyz/ai-agents-llms/switchboard-agent-skill/switchboard-crossbar-ops

GET /updates/iota/{network}/{aggregatorAddresses} to build Iota update payloads. Example uses mainnet network and an aggregator ID.

```bash
curl "$CROSSBAR/updates/iota/mainnet/$AGGREGATOR_ID"
```

--------------------------------

### Run Price Feeds Example

Source: https://docs.switchboard.xyz/docs-by-chain/evm/monad

Runs the price feeds example on the fastest testnet path. If CONTRACT_ADDRESS is unset, it deploys a fresh consumer before submitting the v2 update.

```bash
bun run example

```

--------------------------------

### Build Sui update payloads

Source: https://docs.switchboard.xyz/ai-agents-llms/switchboard-agent-skill/switchboard-crossbar-ops

GET /updates/sui/{network}/{aggregatorAddresses} to build Sui update payloads. Example uses mainnet network and an aggregator ID.

```bash
curl "$CROSSBAR/updates/sui/mainnet/$AGGREGATOR_ID"
```

--------------------------------

### Run the Conversion Example

Source: https://docs.switchboard.xyz/docs-by-chain/evm/surge/surge-tutorial

Runs the surge-convert script with sample data or a custom surge data file specified via the SURGE_DATA_FILE environment variable.

```bash
# With sample data
bun run surge-convert

# With custom surge data file
SURGE_DATA_FILE=path/to/surge-data.json bun run surge-convert

```

--------------------------------

### Build Aptos update payloads

Source: https://docs.switchboard.xyz/ai-agents-llms/switchboard-agent-skill/switchboard-crossbar-ops

GET /updates/aptos/{network}/{aggregatorAddresses} to build Aptos update payloads. Example uses testnet network and an aggregator ID.

```bash
curl "$CROSSBAR/updates/aptos/testnet/$AGGREGATOR_ID"
```

--------------------------------

### Simulate one or more v2 feed hashes

Source: https://docs.switchboard.xyz/ai-agents-llms/switchboard-agent-skill/switchboard-crossbar-ops

GET /v2/simulate/{feedHashes} to simulate one or more v2 feed hashes. Example uses network=testnet query parameter.

```bash
curl "$CROSSBAR/v2/simulate/$FEED_ID?network=testnet"
```

--------------------------------

### Connect to Surge and stream real-time prices

Source: https://docs.switchboard.xyz/docs-by-chain/solana-svm/surge/surge-tutorial

Initializes the Surge client, loads environment, discovers available feeds, subscribes to BTC/USD and SOL/USD, and handles signed price updates with latency metrics. Requires an active Surge subscription; otherwise connectAndSubscribe fails.

```typescript
import * as sb from "@switchboard-xyz/on-demand";

// Load environment (keypair, connection, queue, etc.)
const { keypair, connection, queue } = await sb.AnchorUtils.loadEnv();

// Initialize Surge client with keypair and connection
const surge = new sb.Surge({ connection, keypair });

// Auth note: the SDK signs with your keypair to authenticate the session.
// If the keypair has no active Surge subscription, connectAndSubscribe will fail.

// Discover available feeds
const availableFeeds = await surge.getSurgeFeeds();
console.log(`Found ${availableFeeds.length} available feeds`);

// Subscribe to price feeds
await surge.connectAndSubscribe([
  { symbol: 'BTC/USD' },
  { symbol: 'SOL/USD' },
]);

// Handle real-time updates
surge.on('signedPriceUpdate', async (response: sb.SurgeUpdate) => {
  const metrics = response.getLatencyMetrics();

  // Skip heartbeat messages
  if (metrics.isHeartbeat) return;

  const prices = response.getFormattedPrices();

  metrics.perFeedMetrics.forEach((feed) => {
    console.log(`${feed.symbol}: ${prices[feed.feed_hash]}`);
    console.log(`  Source → Oracle: ${feed.sourceToOracleMs}ms`);
    console.log(`  Emit Latency: ${feed.emitLatencyMs}ms`);
  });
});
```

--------------------------------

### Build v2 chain-specific update payloads

Source: https://docs.switchboard.xyz/ai-agents-llms/switchboard-agent-skill/switchboard-crossbar-ops

GET /v2/update/{feedHashes} to build v2 chain-specific update payloads. Example uses chain=evm, network=testnet, and use_timestamp=true query parameters.

```bash
curl "$CROSSBAR/v2/update/$FEED_ID?chain=evm&network=testnet&use_timestamp=true"
```
Tokens:
Raw