Suggested frameworks

Hosted proxy architecture

Bags runs the payment layer for you — the 402 challenge, payment verification, settlement, and catalog discovery all live in the hosted proxy. Your backend stays untouched:

What Bags forwards to your API

One payment link maps to exactly one targetUrl — no path passthrough; create one link per endpoint. Query strings pass through (caller params are merged onto the targetUrl). All standard methods are supported; bodies are forwarded for POST / PUT / PATCH.

Request headers are allowlisted: only content-type, accept, accept-language, user-agent, and x-bags-* reach your API. Authorization and Cookie never do — agents can't smuggle credentials.

Pricing: flat or metered

• exact (default) — every paid call settles the link amount.
• upto — the link amount is a ceiling. Your API declares the actual usage per call in an x-bags-settle-amount response header (decimal USD), and only that settles. Missing header settles the ceiling; 0 delivers the response free. upto is EVM-only.

Protect your API from paywall bypass

Every proxied request is signed, so your server can tell a paid call apart from someone hitting your targetUrl directly.

Each request carries x-bags-proxy-signature (t=<unix-seconds>,v1=<hex hmac>) and x-bags-proxy-timestamp. The signature is HMAC-SHA256 over:

{timestamp}.{METHOD}.{pathWithQuery}.{sha256HexOfRawBody}

Fetch your signing key once and store it server-side:

curl https://www.getbags.app/api/merchant/proxy-signing-secret \
  -H "Authorization: Bearer <your key from Dashboard → Developers>"

Verify by recomputing the HMAC over the raw body (constant-time compare, reject timestamps older than ~5 minutes) and reject unsigned requests — while still accepting your existing customers' API keys.

Failure semantics

Payment is verified first, your endpoint is called, and funds settle only when you respond with HTTP < 400. A wallet is never silently charged for a failed request:

Responses stream end-to-end (SSE and LLM token streams included); the first byte reaches the agent after settlement. upto usage must be declared in headers before the body starts.

Test it end-to-end

1. Create a payment link on a testnet (e.g. base_sepolia) with the dashboard in test mode
2. curl your x402 URL — you should see the 402 payment instructions
3. Pay it like a buyer would: any x402-capable client funded with testnet USDC from Circle's faucet
4. Confirm the payment appears in your dashboard and the call reached your API signed

Next