Chainlink Oracles

Agent budgets are almost always denominated in one currency while settlement happens in another. A USD budget settles in USDC; a EUR budget settles in a stablecoin priced in USD; a Solana agent pays gas in SOL and earns in USDC. Chio handles these conversions through the chio-link crate, which reads prices from Chainlink Data Feeds and Pyth, applies staleness and confidence rules, and attaches oracle evidence to every settlement receipt so the chosen price is auditable after the fact.

Why Oracles in a Trust Kernel

Trust comes apart when one side of a transaction can dictate the price. A kernel that authorises a "$10 of API time" capability but then lets the seller choose the exchange rate turns the budget into a suggestion. Oracles pin both sides to a public price at a public time, so a settlement receipt can be verified against the same oracle reading by any third party.

The integration is policy-level, not runtime-level: chio never executes a swap. It reads prices, applies a configurable margin, and records which oracle reading it used in the receipt. If an oracle is stale or a sequencer is down, the kernel fails closed rather than falling back to a less trusted price.

Supported Oracle Stacks

Oracle	Chains	Typical cadence
Chainlink Data Feeds	Ethereum Mainnet · Base · Arbitrum · Optimism · Solana	Heartbeat 1 h; trigger 0.5% to 2% deviation
Pyth Network (Hermès)	Ethereum Mainnet · Base · Arbitrum · Optimism · Solana	Pull-based; ~400 ms publish cadence

Deployments typically pick Chainlink as the canonical source and Pyth as a corroborating sanity check. If the two disagree beyond a configured tolerance, chio denies the conversion and emits a denial receipt with oracle_disagreement as the reason.

How a Price Gets Consumed

rendering…

A price read is a four-step process: fetch, validate, convert, stamp. Each step can reject, and rejection fails the enclosing capability evaluation rather than silently degrading.

Freshness and Confidence

Each configured feed carries a staleness window and, where the oracle exposes one, a confidence interval. A reading is rejected if either threshold fails. Defaults are chosen per feed class:

Stablecoin pairs (USDC/USD, USDT/USD): 60 s staleness window, 0.5% confidence interval. Tight because the expected variance is near zero.
Major crypto pairs (ETH/USD, BTC/USD, SOL/USD): 120 s staleness window, 1% confidence interval.
Long-tail pairs (smaller L1 native tokens, regional stablecoins): 300 s staleness window, 2% confidence interval. Longer heartbeats on these feeds force looser freshness.

Any of these can be overridden per deployment. Overrides are loaded at sidecar boot and enforced for every subsequent call.

FX Conversion with Margin

Once a price passes its checks, chio applies an operator-configured FX margin before quoting the converted amount. Margins protect both sides against the short window between price read and on-chain execution. A typical production margin is 25 to 50 bps on stablecoin pairs and 100 bps on volatile pairs.

yaml

# sidecar/link.yaml
feeds:
  - pair: "USDC/USD"
    chainlink: "0x7e860098f58bbfc8648a4311b374b1d669a2bc6b"   # Base
    pyth_id: "0xeaa020c61cc479712813461ce153894a96a6c00b21ed0cfc2798d1f9a9e9c94a"
    staleness_secs: 60
    confidence_bps: 50
    fx_margin_bps: 25

  - pair: "ETH/USD"
    chainlink: "0x71041dddad3595f9ced3dccfbe3d1f4b0a16bb70"   # Base
    pyth_id: "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace"
    staleness_secs: 120
    confidence_bps: 100
    fx_margin_bps: 100

l2_health:
  sequencer_feed: "0xbcf85224fc0756b9fa45aa7892530b47e10b6433"  # Base
  max_downtime_secs: 30

Circuit Breakers and Sequencer Health

Two operational conditions trigger an automatic circuit break on oracle-backed conversions:

Feed outage · N consecutive reads return stale timestamps or revert. After the threshold, the feed is marked unhealthy and conversions against it deny until it recovers.
L2 sequencer downtime · On optimistic L2s a frozen sequencer can keep a feed's on-chain timestamp advancing while the underlying price has not actually updated. Chio reads the L2SequencerUptimeFeed contract and denies conversions when the sequencer has been down longer than the configured threshold.

Fail closed on oracle uncertainty

A denied conversion is always cheaper than an overpaid settlement. Operators can configure fallback behaviour (soft-fail to a conservative price, queue the decision for human review), but the default is to deny and emit a signed denial receipt so the client knows exactly why the call failed.

Oracle Evidence in Receipts

When a conversion succeeds, chio attaches an OracleConversionEvidence block to the resulting receipt. The block records which readings were consulted, the applied margin, and the final rate used. Anyone holding the receipt can replay the conversion deterministically.

json

{
  "oracle_evidence": {
    "pair": "USDC/USD",
    "readings": [
      {
        "source": "chainlink",
        "chain": "eip155:8453",
        "feed_address": "0x7e86...bc6b",
        "round_id": "18446744073709562042",
        "answer": "99980000",
        "decimals": 8,
        "updated_at": 1760923400
      },
      {
        "source": "pyth",
        "price_id": "0xeaa0...9c94a",
        "price": 0.99982,
        "conf": 0.00014,
        "publish_time": 1760923399
      }
    ],
    "applied_margin_bps": 25,
    "final_rate": 0.99955,
    "direction": "USD_to_USDC"
  }
}

Next Steps

Settlement · the on-chain execution layer that consumes oracle-backed quotes
Budgets & Metering · how cross-currency budgets are authored and enforced
x402 Payments · agent-level payments where oracle quotes feed per-request pricing

PreviousSettlement Nextx402 Payments