ValidPay

ValidPay is an open-source x402 gateway for API sellers: settle USDC only when the upstream response matches your contract — bad payloads withhold payment.

Comment

Track 2 — Agentic Commerce & Payment Infrastructure

Inspiration

If you sell an API to agents, they call it in loops and pay per request. x402 made that possible — but most integrations settle as soon as payment verifies, before anyone checks the response. You can get paid for error JSON or empty junk; buyers stop trusting the endpoint.

We built ValidPay so API sellers can offer pay-per-request APIs with a simple promise: you only get paid when the response matches the contract you declared.

What it does

ValidPay is a configurable seller-side x402 gateway:

  1. Seller declares routes in validpay.config.json (path, price, upstream URL, response contract)
  2. Buyer/agent hits the gateway → 402 → signs payment → retries
  3. Gateway proxies to upstream and checks the contract
  4. Fail → 422 · settlement canceled · buyer receipt rejected · no on-chain charge
  5. Pass → 200 · buyer receipt paid · USDC settles on Algorand Mainnet

Live demo: https://validpay.uk — Open-Meteo is a sample upstream (not the product). Illegal coordinates withhold; Berlin forecast settles. Sellers replace the upstream in config.

Seller console at /dashboard/ — Settled / Withheld (+ upstream errors) and a live feed for the person running the gateway.

What we're not: a marketplace, reputation registry, or LLM quality judge (v1 = mechanical contracts).

What's different

Most x402 demos stop at “payment verified → settle.” ValidPay adds one gate: settlement waits for the response contract. That makes “pay for usable data” an installable seller tool, not a one-off demo script.

Technical highlights

  • Full x402 loop on Algorand Mainnet via GoPlausible
  • Conditional settlement via @x402/core lifecycle hooks (422 → cancel)
  • Config-driven routes + declarative JSON contracts
  • Buyer receipts (paid / rejected + reason) plus settlement header when paid
  • Public HTTPS demo (validpay.uk) + txs in docs/hackathon/VERIFIED_DEMO.md

How we built it

  • Gateway: Express + @x402/express · Algorand Mainnet (@x402/avm)
  • Config: validpay.config.json → routes, upstream, contract
  • Client demos: @x402/fetch + Algorand buyer key (demo-agent/)
  • Console: static UI + /v1/dashboard audit feed

Challenges we ran into

  • Settlement timing: validate-then-settle — handler failure → onVerifiedPaymentCanceled
  • Roles: upstream ≠ x402 payee; seller is the gateway payTo

Accomplishments that we're proud of

  • Live Mainnet path: withhold on error payload, settle on valid forecast (tx on Lora)
  • Open-source shaped for API developers to clone and cover their own APIs

What we learned

  • x402 lifecycle hooks are the right extension point for “pay if valid”
  • Seller tooling needs an operator console; buyers only need clear receipts

What's next for ValidPay

  • Persist audit log · richer contract errors · more hosted utility routes
  • Later: marketplace

Testing instructions

Built With

Share this project:

Updates