Scanner evidence

Common x402 Implementation Mistakes

These are not generic best practices. They are the concrete warning classes Ontario's readiness scanner emits when an x402 endpoint is hard for agents to discover, price, or pay safely.

Missing accepts entries

A paid endpoint can return HTTP 402 but still fail agent integration if the response body lacks a machine-readable accepts array. Agents need the accepted scheme, network, asset, amount, resource, and expiry before they can construct a payment.

Evidence: Scanner warning: accepts_missing. Smoke baseline requires paid Ontario endpoints to expose accepts[0] plus a decodable PAYMENT-REQUIRED header.

Fix: Return x402Version and accepts[0] in the 402 body, and keep PAYMENT-REQUIRED compatible for clients that read headers first.

Network mismatch

Agents budget and sign for a specific network. A manifest that says one network while the payment challenge uses another can cause failed payment attempts or policy denial.

Evidence: Scanner warning: network_mismatch. Ontario compares endpoint challenge metadata against manifest metadata.

Fix: Use one canonical network value across /.well-known/x402.json, OpenAPI docs, and live 402 requirements.

Invalid price format

Human-readable prices are not enough. Agents need parseable atomic amounts and a stable asset/network pair.

Evidence: Scanner warning: invalid_price_format. Ontario penalizes ambiguous or non-machine-readable price fields.

Fix: Publish maxAmountRequired as an atomic integer string and expose price_usdc only as a display helper.

Stale manifests

A manifest that never changes may be abandoned. Agents should prefer recent metadata for paid endpoints.

Evidence: Scanner warning: manifest_stale. Service profiles track history and freshness.

Fix: Update generated_at or last_updated when endpoint price, network, method, schema, or facilitator metadata changes.

Facilitator metadata gaps

Without facilitator metadata, clients cannot reason about verification and settlement paths.

Evidence: Scanner warning: facilitator_metadata_gap. Ontario exposes facilitator support and checks for discoverable payment infrastructure.

Fix: Publish facilitator URL, network support, accepted assets, and settlement expectations where agents can read them.

Sources

Run the readiness checker