> 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/ai-agents-llms/switchboard-agent-skill/switchboard-feed-design.md). # Switchboard Feed Design Skill ## Purpose Turn a data requirement into a robust, verifiable feed definition: * Design `OracleJob[]` pipelines with stable parsing and source diversity * Normalize scaling/decimals consistently * Choose aggregation strategy and consumer validation policy defaults * Identify and mitigate substitution, outliers, and schema brittleness risks ## Dependencies Use exact pins from the [SDK Version Matrix](/tooling/sdk-version-matrix.md). * `@switchboard-xyz/common@5.8.2` This skill designs feed definitions. Integration details (atomic update+use, on-chain verifier patterns) belong to chain-specific skills. ## Preconditions * `OperatorPolicy` exists (especially if paid APIs, X402, or job storage is involved). ## Inputs to Collect Required: * target metric (price/index/rate/event outcome) and units * target chain(s) and consumer type (how the value will be used) * value-at-risk / criticality (UI display vs liquidation vs settlement) * allowed/forbidden sources * required secrets (API keys, auth headers, payment headers) Optional (only if relevant): * expected request frequency / external API rate limits * This matters if the user plans to run a crank/keeper or high-frequency bots. * On-demand does not impose a cadence by itself, but your infrastructure and upstream APIs still do. ## Security Invariants * Variable overrides are secrets-only. * Hardcode market IDs, selectors, URLs, JSON paths, multipliers in the job definition. * Prefer 3+ independent sources when possible. ## Minimal Example ```json { "tasks": [ { "httpTask": { "url": "https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT" } }, { "jsonParseTask": { "path": "$.price" } }, { "multiplyTask": { "big": "1e18" } } ] } ``` ## Playbook ### 1) Specify output contract Define: * numeric scaling (e.g., 1e18) * signedness (allow negative or not) * bounds and failure mode (reject vs clamp) ### 2) Choose sources * diversify upstream origins (avoid mirrored endpoints) * prefer reliable schemas with stable versioning * add at least one fallback source where possible * commonly used free spot APIs (availability varies by region): Binance, Coinbase, Kraken, Bitstamp, OKX ### 3) Production templates Template 1: Single source (tutorial baseline) ```json { "tasks": [ { "httpTask": { "url": "https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.price" } }, { "multiplyTask": { "big": "100000000" } } ] } ``` Template 2: 3-source median (production minimum, 2 of 3 required) ```json { "tasks": [ { "medianTask": { "min_successful_required": 2, "jobs": [ { "tasks": [ { "httpTask": { "url": "https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.price" } }, { "multiplyTask": { "big": "100000000" } } ] }, { "tasks": [ { "httpTask": { "url": "https://api.kraken.com/0/public/Ticker?pair=XBTUSD", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.result.XXBTZUSD.c.0" } }, { "multiplyTask": { "big": "100000000" } } ] }, { "tasks": [ { "httpTask": { "url": "https://api.coinbase.com/v2/prices/spot?currency=USD", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.data.amount" } }, { "multiplyTask": { "big": "100000000" } } ] } ] } } ] } ``` Template 3: 5-source with fallback tolerance (production recommended). In `MedianTask`, `max_range_percent` is a human percent string. ```json { "tasks": [ { "medianTask": { "min_successful_required": 3, "max_range_percent": "2.5", "jobs": [ { "tasks": [ { "httpTask": { "url": "https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.price" } }, { "multiplyTask": { "big": "100000000" } } ] }, { "tasks": [ { "httpTask": { "url": "https://api.coinbase.com/v2/prices/spot?currency=USD", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.data.amount" } }, { "multiplyTask": { "big": "100000000" } } ] }, { "tasks": [ { "httpTask": { "url": "https://api.kraken.com/0/public/Ticker?pair=XBTUSD", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.result.XXBTZUSD.c.0" } }, { "multiplyTask": { "big": "100000000" } } ] }, { "tasks": [ { "httpTask": { "url": "https://www.bitstamp.net/api/v2/ticker/btcusd/", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.last" } }, { "multiplyTask": { "big": "100000000" } } ] }, { "tasks": [ { "httpTask": { "url": "https://www.okx.com/api/v5/market/ticker?instId=BTC-USD", "method": "METHOD_GET" } }, { "jsonParseTask": { "path": "$.data[0].last" } }, { "multiplyTask": { "big": "100000000" } } ] } ] } } ] } ``` Template 4: Custom API with auth headers (variable override pattern) ```json { "tasks": [ { "httpTask": { "url": "https://api.provider.com/v1/markets/btc-usd/spot", "method": "METHOD_GET", "headers": [ { "key": "Authorization", "value": "Bearer ${ACCESS_TOKEN}" }, { "key": "X-API-Key", "value": "${API_KEY}" } ] } }, { "jsonParseTask": { "path": "$.data.price" } }, { "multiplyTask": { "big": "100000000" } } ] } ``` Variable override rule reminder: * only use `${...}` for auth credentials (keys/tokens) * never use `${...}` for URLs, paths, symbols, multipliers, or selection logic ### 4) Error handling and rate limiting * set `min_successful_required` so one source outage does not break updates (for example 2-of-3, 3-of-5) * set `max_range_percent` for drift/outlier protection before median is accepted; this `MedianTask` field is a human percent string, not the raw v2 feed-level `maxJobRangePct` scale * stagger polling and cap request rate to provider quotas (especially free tiers) * back off exponentially on HTTP 429/5xx and keep at least 3 independent sources ### 5) Recommended Validation Defaults (suggest, don’t enforce) These are primarily **consumer policy defaults** (freshness/deviation) and **oracle sample requirements** (responses/signatures) that you apply when verifying/using the feed. * Start from `OperatorPolicy` presets in the top-level [Switchboard Skill](/ai-agents-llms/switchboard-agent-skill.md), then tune per feed risk and volatility. * `minResponses` / `minSampleSize`: 3 for higher-risk flows; 1 for dev/non-critical * aggregation: median (or median-of-means where supported) * deviation: * majors: 100–200 bps for high-risk flows; \~500 bps for standard flows * long-tail / volatile: wider deviation may be needed as an explicit override from preset defaults * staleness: * bots/liquidations: 15–60 seconds (or chain-equivalent) * UI/general: 60–300 seconds ### 6) Produce outputs Produce a `FeedBlueprint` including: * `OracleJob[]` JSON * sources + rationale * aggregation choice * required secrets and override variable names * suggested consumer validation defaults (staleness/deviation/min responses) * simulation plan (Crossbar or local job runner) ## References * * * --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.switchboard.xyz/ai-agents-llms/switchboard-agent-skill/switchboard-feed-design.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.