Build with TypeScript

Design, simulate, and publish Switchboard feed definitions using TypeScript (Solana and EVM compatible patterns).

This guide is for developers who prefer code-first workflows.

You’ll learn how to:

• model a feed as a list of Oracle Jobs

• compose each job from sequential Tasks

• simulate jobs using Crossbar

• iterate safely and build production-grade feed definitions

This guide focuses on designing + simulating feed definitions. Deployment differs by chain — see Deploy Feed.

---

Mental model

Oracle Jobs are “pipelines”

A job is an ordered list of tasks:

// Oracle Job
[
  httpTask,
  jsonParseTask,
  multiplyTask,
]

Each task runs sequentially. The job’s “current value” is updated as tasks run, and the job result is valid only if the final task produces a numeric value.

Feeds are “job sets”

A feed is a set of jobs. Oracles execute the jobs and then aggregate the results (commonly median across jobs).

---

Prerequisites

• Node.js or Bun (examples use Bun for simple TS execution)

• Basic TypeScript familiarity

• Your data sources (REST APIs, DEX pricing tasks, etc.)

---

Install dependencies

Using Bun

mkdir example
cd example
bun init
bun add @switchboard-xyz/on-demand@3.10.6 @switchboard-xyz/common@5.8.5

Note: Some examples import OracleJob from @switchboard-xyz/common. Adding it explicitly avoids “transitive dependency” surprises.

Keep these versions together and refresh your lockfile when upgrading. Common 5.8.5 uses the Rust/prost-compatible canonical encoding for OracleJob and OracleFeed identities. It preserves newer task fields and explicitly set optional defaults, and its encoder is isolated from other installed Common versions.

---

Example: a minimal BTC/USDT job

This is the smallest “real” job: fetch a JSON payload and extract a price.

Create index.ts:

import { OracleJob, serializeOracleJob } from "@switchboard-xyz/common";

const jobs: OracleJob[] = [
  OracleJob.fromObject({
    tasks: [
      {
        httpTask: {
          url: "https://binance.com/api/v3/ticker/price?symbol=BTCUSDT",
        },
      },
      {
        jsonParseTask: {
          path: "$.price",
        },
      },
    ],
  }),
];

console.log("Jobs JSON:\n");
console.log(JSON.stringify({ jobs: jobs.map((j) => j.toJSON()) }, null, 2));

At this point you have a valid feed definition (one job).

---

Simulate your job(s) with Crossbar

Simulation runs your jobs against real sources and returns their outputs. This is how you iterate quickly before deploying or publishing.

⚠️ The public simulation endpoint is heavily rate-limited. Use it for development only.

Append this to index.ts:

// Serialize the jobs to base64 strings.
const serializedJobs = jobs.map((oracleJob) => {
  const base64 = serializeOracleJob(oracleJob).toString("base64");
  return base64;
});

console.log("\nRunning simulation...\n");

// Call the simulation server.
const response = await fetch("https://crossbar.switchboard.xyz/api/simulate", {
  method: "POST",
  headers: [["Content-Type", "application/json"]],
  body: JSON.stringify({
    cluster: "Mainnet",
    jobs: serializedJobs,
  }),
});

// Print results
if (response.ok) {
  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
} else {
  console.error(`Simulation failed (${response.status})`);
  console.error(await response.text());
}

Run it:

bun run index.ts

You should see a response like:

{
  "results": ["64158.33000000"],
  "version": "..."
}

---

Building production-grade feeds

Use multiple jobs (multiple sources)

The simplest reliability upgrade is to use several independent jobs:

• Job 1: CEX API

• Job 2: another CEX API

• Job 3: on-chain DEX price simulation task

Then rely on aggregation (median) and feed configuration (variance/quorum) to filter noise.

Conceptually:

const jobs: OracleJob[] = [
  /* source A */,
  /* source B */,
  /* source C */,
];

Normalize decimals

Different sources often report:

• different quote assets

• inverted prices

• different decimal precision

Use math tasks (multiply/divide/round) so every job returns the same unit.

Bound results (optional but recommended)

Bounding can be applied:

• within a job (reject a single bad API response)

• at the feed level (reject updates when jobs disagree too much)

Feed-level validation fields use different units depending on the surface. Raw v2 OracleFeed.maxJobRangePct is scaled by 1e9 (1_000_000_000 = 1%), while MedianTask.max_range_percent is a human percent string. See Feed Parameter Units before publishing a feed definition.

---

Task reference

Switchboard supports many task types, including:

• HttpTask (REST)

• JsonParseTask (JSONPath extraction)

• MedianTask (sub-aggregation inside a job)

• JupiterSwapTask (Solana DEX price simulation)

• SecretsTask (secure secret retrieval)

Full task docs:

• Task Types Reference

---

Secrets, variables, and safety

Variable overrides (${VAR_NAME})

Use variable overrides to insert request-scoped values into task string fields at runtime. API keys and auth tokens are the safest default because they do not intentionally change feed semantics.

See Data Feed Variable Overrides for the supported pattern and the full security guidance.

Override values are not included in the feed ID or signed checksum. Keep data sources, selections, and calculations fixed for permissionlessly updated feeds. Semantic overrides are supported when a controlled updater owns the request and consumers intentionally trust that caller.

---

Where to go next

• Deploy on-chain

• Use the visual editor