Proxy Flow

Understand how the hosted proxy enforces Coinbase x402 payments before forwarding requests to your API.

Handshake Sequence

  1. No X-PAYMENT header → x402Nova returns HTTP 402 with Coinbase payment requirements.
  2. The agent uses Coinbase's buyer SDK to mint an X-PAYMENT header.
  3. The proxy posts that header to the facilitator's /verify endpoint.
  4. On success we call /settle so the operator wallet signs and pays the developer.
  5. x402Nova forwards the original request (plus any configured headers) to your API.
  6. The agent receives your response and an X-PAYMENT-RESPONSE header with receipt details.
  7. Firestore logs buyer/payment/volume metrics for the route.

Minimal Backend Changes

Your API keeps doing what it already does. Here's the Express snippet from example/src/server.ts:

app.post("/x402/test", requireApiKey, (_req, res) => {
  res.json({ message: "You accessed the x402-protected resource." });
});

Requests still include any headers you configured on the route, so you can preserve internal API keys or tenancy context.