Payments (x402)

Olbos is paid for in-band, by the agent, in USDC — no signups, no API keys, no invoices. This is what x402 is for: HTTP 402 Payment Required, made real. This doc covers how it works, why the funding payment is the deposit, and what each call costs.

x402 in one paragraph

x402 turns the dormant HTTP 402 Payment Required status into a working payment flow. A client requests a paid resource; the server responds 402 with payment requirements (amount, asset, recipient, network); the client signs a payment and retries with it attached; the server verifies and settles the payment through a facilitator and then serves the resource. For an agent, this is just "the request costs money," handled by the SDK transparently.

The rail seam

Olbos isolates x402 behind a PaymentRail interface so the core never depends on a specific facilitator or even on x402 at all:

• DevRail (localnet) — auto-approves and fabricates a settlement reference, so the full event flow (including x402.payment.received) runs without real USDC. Selected by default; the demo uses an x-dev-payer header to identify the payer.
• X402Rail (real) — genuine x402 over the PayAI facilitator, on devnet or mainnet. Selected with OLBOS_RAIL=x402.

Both implement one method, collect(req, res, charge), which either returns a settled payment or writes the 402 challenge and returns "not paid." Swapping facilitators is a rail change, nothing else.

The facilitator — and why it's gasless

Olbos uses the PayAI facilitator (facilitator.payai.network). Two properties matter:

• It supports Solana mainnet — network solana (and the CAIP-2 form solana:5eykt4...), with USDC.
• It sponsors the fee payer. The facilitator provides a feePayer in the payment requirements, so the agent never needs SOL — payments settle gasless. Agents hold USDC, not gas. This is verified live: the mainnet 402 challenge carries the facilitator's sponsored feePayer.

The facilitator is a trust dependency for payments (its compromise can disrupt settlement) but not for custody — it can never touch funds in a Swig. A production deployment should plan a fallback (a second facilitator, or running our own).

Payment-as-deposit: the key insight

For the fund call, the x402 settlement transfer is itself the deposit. There is no "the agent sends money, then separately tells us about it" race — the settled on-chain transfer of USDC is the funding event. The engine routes the settled USDC into the strategy's Swig wallet PDA and credits it. One action, no reconciliation gap.

A safety guard backs this: at boot the API refuses to start if the rail's settlement mint differs from the engine's deposit mint, or if a mainnet rail is paired with a non-mainnet config. "Payment is the deposit" must never silently become a lie about which asset arrived.

Pricing

Metered calls and their cost:

Reads are free; only state-changing calls are metered. Each metered call is paid transparently by the agent's SDK — no signups, no API keys.

The engine as a buyer, too

Olbos isn't only a seller. The engine can pay for premium inputs over x402 — e.g. a premium APY data feed — through a spend-capped DataClient. Each purchase is logged as x402.payment.sent. This demonstrates the symmetry of the agent economy: the same protocol that funds the treasury also lets the treasury engine buy what it needs, under a budget.

What an agent actually does

In x402 mode the agent never touches any of this directly — the SDK does:

1. The agent calls a metered method.
2. The SDK's x402 client hits the endpoint, receives the 402, signs the payment with the agent's keypair, and retries.
3. The facilitator settles (gasless); the server serves the result.
4. The agent gets a normal return value.

From the agent's perspective, "this call costs USDC" is the entire mental model.

Next: Agents quickstart · Custody.