x402 payment flow

Payment enforcement happens at the Caddy gateway. The API publishes payment requirements through discovery and OpenAPI; the gateway verifies and settles via the facilitator.

1. Preflight Call a paid route without PAYMENT-SIGNATURE. Gateway returns 402 with PAYMENT-REQUIRED.

2. Sign Client wallet builds and signs the USDC transfer payload expected by the facilitator.

3. Retry Resend the request with PAYMENT-SIGNATURE. Caddy verifies and settles via facilitator.

4. Success Paid route returns 200 and may include PAYMENT-RESPONSE settlement metadata.

Required headers

PAYMENT-REQUIRED — returned on initial paid preflight (402).
PAYMENT-SIGNATURE — client retry header containing signed payment payload.
PAYMENT-RESPONSE — optional success header with settlement receipt metadata.

Typical accept policy fields

scheme: usually exact
network: e.g. algorand-mainnet
asset: USDC ASA id on Algorand mainnet
payTo: receiver address configured for the gateway
maxAmountRequired: USDC-denominated amount for the route (e.g. 0.01).

Per-route pricing

Most paid routes default to 0.01 USDC. Wallet-personalized opportunities at /opportunities/personalized are priced separately (currently 0.05 USDC). See the endpoint catalog for current values from discovery metadata.

Common failure modes

402 without signature — expected preflight behavior.
Malformed signature — gateway/facilitator rejects before upstream call.
Expired proof — retry with a fresh signed payload.
Policy mismatch — network, asset id, payTo, or amount do not match discovery/Caddy policy.

curl -i https://canix402-api.compx.io/opportunities