x402 Onchain Router

What problem does it solve?

Smart contracts are sandboxed. They cannot make HTTP requests, and even if they could, they have no way to pay for them. No credit card, no API key, no identity that any off-chain service would recognize. Even with the x402 Protocol enabling stablecoin payments for API access, that framework requires signing off-chain messages, which smart contracts cannot do. So any onchain logic that depends on real-world data or paid external services ends up relying on a trusted middleman: a relayer, a keeper, or a centralized oracle that someone has to run and trust.

What is it?

The x402 Onchain Router is an end-to-end system that lets smart contracts autonomously trigger paid HTTP API calls and receive the results back onchain. No API keys, no manual intervention.

The contract's onchain address is its identity. Escrowed USDC is its payment method. Chainlink CRE is the decentralized execution layer that reaches consensus on the result before writing it back.

How does it work?

A user deposits USDC into HTTPayerRouter and calls requestExecution(url, method, payload, maxCost). The contract escrows the funds and emits an ExecutionRequested event.

Chainlink CRE detects the event via a log trigger. Each DON node independently calls the HTTPayer proxy, passing the requestId.

The proxy verifies the request is legitimate by reading the contract state onchain. It then makes the HTTP call to the target API, floating an x402 micropayment, a USDC payment embedded directly in the HTTP request header, with no API key required.

To ensure DON consensus, the proxy caches results by requestId. All nodes receive the same response regardless of when they call.

The CRE workflow ABI-encodes the result and calls writeReport, which invokes HTTPayerRouter.onReport(). The contract validates that the call came from the legitimate CRE forwarder, then settles: actualCost USDC goes to the HTTPayer treasury, the remainder is refunded to the user, and the result is stored onchain.

Demo: AI-Driven Portfolio Rebalancer

To show the system end-to-end, we built AIRebalancer: a contract that holds a mock portfolio split between wBTC and a yield stablecoin. It uses the HTTPayer system to call an AI macro regime oracle (InvestBudAI, gated behind x402 at $0.01/call) to determine whether market conditions are Risk-On or Risk-Off, then rebalances the portfolio allocation onchain automatically.

The full loop from the user clicking "Request Regime" to the portfolio bar updating requires zero off-chain coordination beyond running the proxy and the CRE workflow.

Smart Contracts (Solidity, Base Sepolia)

HTTPayerRouter.sol handles USDC deposits, request escrow, CRE callback validation, and settlement. AIRebalancer.sol is the demo contract that calls the router to fetch an AI regime signal and applies it to a mock wBTC/stablecoin portfolio.

Chainlink CRE Workflow (TypeScript)

A log trigger listens for ExecutionRequested events from HTTPayerRouter. Each DON node independently calls the HTTPayer proxy via HTTPClient. The result is ABI-encoded and written back via evmClient.writeReport(), which calls onReport() on the contract.

HTTPayer Proxy (Bun + TypeScript)

An Express server that validates requests against onchain state via viem. It executes x402 micropayments by probing the target URL for a 402 response, parsing payment instructions, constructing a signed USDC payment header, and retrying the request. An in-memory idempotency cache ensures all DON nodes receive identical responses for the same requestId.

Frontend (React + Vite + wagmi)

Wallet connect, USDC approval, and fund/withdraw flows. A one-click "Request Regime" button triggers live CRE polling, then an "Apply Regime" step with an animated portfolio bar showing the rebalance. Contract addresses are loaded directly from deployment JSON files.

Automation (Python)

cre_watcher.py polls for ExecutionRequested events and automatically calls cre workflow simulate for each new request, with persistent state to avoid double-processing.