DOCS / THE PAYER LOOP

Walk in with money, leave with a guarded plan

An external agent needs exactly two things from a transaction layer: data it can pay for without an account, and plans it can trust without reading calldata. This demo does both in one script — an x402 payment through the routing engine, then a dryRun job — against the same rails the chat uses.

Run it

YF_API_KEY=yf_…  npx tsx scripts/x402-payer-demo.ts
# no key? .env.local PRIVATE_KEY → the script SIWE-mints one for you
# flags: --base http://localhost:3000   --ask "…"   --job "…"

Step ① hits POST /api/route — the routing engine as a service (Bearer-only). The engine shortlists, picks a paid endpoint, pays it over x402 (≤$0.05, gasless EIP-3009, settled on Base), and streams the receipts. Step ② hits POST /api/jobs with dryRun: true — the full compound plan, step 1 built and guard-checked against live venues, nothing created, $0.

A real run

① POST /api/route — "What are the top crypto news headlines right now?"

  → selected Otto AI ($0.001)
  💸 paying…
  🧾 receipt: Otto AI — $0.001 — tx 0xca2bf8ea3cb46fb8… — ok
  🧾 receipt: ChatGPT — $0.001 — tx 0x6c3466fa2c4dc98c… — ok

  The top crypto news headlines right now are:
  1. South Korea to test tokenized government bonds with CBDC in 2027 …

② POST /api/jobs (dryRun) — "swap 5 usdc from base to arbitrum, then…"

  compiled: Bridge 5 USDC (base) → USDC (arbitrum) → Deposit 4 USDC to
            Hyperliquid → Long $12 of ETH on Hyperliquid → Arm stop-loss (5%)
    0. [sign] Bridge 5 USDC (base) → USDC (arbitrum)
    1. [wait] Solver settles the swap
    2. [sign] Deposit 4 USDC to Hyperliquid
    3. [wait] Hyperliquid credits the deposit
    4. [sign] Long $12 of ETH on Hyperliquid
    5. [auto] Arm stop-loss on ETH (5%)
  step 1 built + guarded against live venues ✓

∑ walked in with money, left with a guarded plan: paid $0.0020 for data, committed $0.

Both receipts are on-chain settlements — every paid call is auditable on /activity. The plan committed nothing: signatures stay with the wallet, and each step is rebuilt and re-guarded when it’s actually offered.

What the agent is trusting (and not)

Not trusting prices: x402 quotes are paid exactly as challenged; the engine refuses endpoints above its cap and your key’s daily budget gates the total.
Not trusting plans: the dryRun preview shows the same artifact + guard report a signature would see — including honest refusals when balances or venues say no.
Trusting one thing: the guard doctrine — models never write calldata, artifacts verify or die.