> For the complete documentation index, see [llms.txt](https://docs.switchboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.switchboard.xyz/custom-feeds/build-and-deploy-feed/build-with-typescript.md).

# Build with TypeScript

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](/custom-feeds/build-and-deploy-feed/deploy-feed.md).

***

## Mental model

### Oracle Jobs are “pipelines”

A job is an ordered list of tasks:

```ts
// 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

```bash
mkdir example
cd example
bun init
bun add @switchboard-xyz/on-demand@3.10.3 @switchboard-xyz/common@5.8.2
```

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

***

## Example: a minimal BTC/USDT job

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

Create `index.ts`:

```ts
import { OracleJob } 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`:

```ts
// Serialize the jobs to base64 strings.
const serializedJobs = jobs.map((oracleJob) => {
  const encoded = OracleJob.encodeDelimited(oracleJob).finish();
  const base64 = Buffer.from(encoded).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:

```bash
bun run index.ts
```

You should see a response like:

```json
{
  "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:

```ts
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](/custom-feeds/advanced-feed-configuration/feed-parameter-units.md) before publishing a feed definition.

***

## Task reference

Switchboard supports many task types, including:

* [HttpTask](/custom-feeds/task-types.md#httptask) (REST)
* [JsonParseTask](/custom-feeds/task-types.md#jsonparsetask) (JSONPath extraction)
* [MedianTask](/custom-feeds/task-types.md#mediantask) (sub-aggregation inside a job)
* [JupiterSwapTask](/custom-feeds/task-types.md#jupiterswaptask) (Solana DEX price simulation)
* [SecretsTask](/custom-feeds/task-types.md#secretstask) (secure secret retrieval)

Full task docs:

* [Task Types Reference](/custom-feeds/task-types.md)

***

## 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](/custom-feeds/advanced-feed-configuration/data-feed-variable-overrides.md) 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](/custom-feeds/build-and-deploy-feed/deploy-feed.md)
* [Use the visual editor](/custom-feeds/build-and-deploy-feed/build-with-ui.md)