Swapper

Swapper is a CLI for agents that need to perform token swaps safely from one command. An agent requests a swap quote, receives an HTTP 402 payment challenge, pays for the request, gets live Base market data, and prepares a policy-checked KeeperHub handoff. The project focuses on the execution boundary: agents should not blindly trade or hold unsafe signing power. Swapper validates the paid quote, checks token allowlists, max notional, chain, and slippage policy, then returns a deterministic handoff receipt and audit summary. For the demo, USDC → cbBTC on Base uses the real cbBTC contract and live market data, while final execution stops at a safe KeeperHub payload preview instead of pretending to submit a live transaction.

Swapper is built as a TypeScript/Hono API deployed on Vercel, with a small CLI demo that acts as the agent. The flow starts with an unpaid /quote request returning HTTP 402, then retries with a demo x402-style payment header to unlock a live quote. Quotes use DexScreener market data on Base, with USDC → cbBTC as the main example using the real cbBTC contract. The backend validates paid quote objects with Zod, applies policy checks for chain, token allowlist, notional size, and slippage, then creates a KeeperHub handoff preview. The hacky-but-useful part is the deterministic handoffHash: it looks like a transaction hash for demo clarity, but is explicitly not an onchain tx. It is a receipt proving the paid quote, policy checks, and payload preview all match. The project also includes OpenAPI docs, automated tests, live Vercel smoke checks, and a concise landing page.