Errors

Three failure modes, no surprises. Billing failures never look like data, and unknown inputs are never charged.

Status codes

Code	Meaning	What to do
`402`	Unpaid: free tier used up, missing `x-client-id` quota, or a paid-only route (ping). A `PAYMENT-REQUIRED` header carries the base64 challenge; the body `accepts[]` lists price in USDC, network and payTo.	Pay with any x402 v2 client and retry with a `payment-signature` header.
`404`	Unknown input with a presented payment (e.g. a mint no upstream knows). The payment is never settled.	Check the address or chain, retry unpaid. You were not charged.
`-32002` (MCP)	Same as 402, over MCP: paid tool past the free tier.	Read `accepts` in the error data, pay, retry with `paymentSignature`.

Verify a settlement receipt

Every paid 200 carries a base64 PAYMENT-RESPONSE header: the settlement receipt with transaction hash, network and amount. Decode it and check the transaction on-chain before crediting anything downstream.

# node: decode the receipt
node -e "console.log(JSON.parse(Buffer.from(
  process.argv[1], 'base64').toString()))" "$PAYMENT_RESPONSE"

gate402 checkouts verify server-side for free — no decoding needed:

curl -X POST https://api.ogenalabs.com/api/gate402/v1/checkout/:id/verify \
  -H 'content-type: application/json' \
  -d '{"paymentSignature":"<base64 x402 PaymentPayload>"}'
# -> {"status":"paid","transaction":"..."} or pending + reason

Verify a risk attestation

Deep reports carry an attestation.digest: the SHA-256 of the report JSON with the attestation, cacheHit and free keys removed. Recompute it locally — a mismatch means the payload was altered after signing. (The companion hmac needs our server key; the digest check is the public half.)

node -e "
const c = require('crypto');
const r = JSON.parse(require('fs').readFileSync(0, 'utf8'));
const { attestation, cacheHit, free, ...core } = r;
const digest = c.createHash('sha256')
  .update(JSON.stringify(core)).digest('hex');
console.log('match:', digest === attestation.digest);
" < deep-report.json

signals.edge probes and gate402 checkouts attest with HMAC only, so there is no public digest to recompute — verify the settlement receipt above (or the free verify endpoint) instead.