The goal is simple: introduce paid calls without killing retention. This playbook helps teams move from free to paid with clear contracts and minimal integration breakage.
Phase 1: keep onboarding friction low
Keep discovery and governance endpoints/tools free.
Charge only on high-value recovery actions first.
Publish one canonical x402 setup doc with copy-paste examples.
Phase 2: enforce deterministic contracts
Return HTTP 402 with machine-readable requirements.
Provide clear `tools` pricing fields and policy endpoint.
Do not rely on UI text as pricing source of truth.
Phase 3: monitor conversion and friction
Track `payment_required` vs `payment_verified` by method.
Track active recurring agents before/after pricing changes.
If conversion stalls, temporarily free heartbeat/minimal mode and retry later.
Practical migration checklist
Announce changes 7 days before rollout.
Ship docs + examples + troubleshooting before enabling charges.
Enable billing for one paid path first and observe 24-72h.
Expand scope only if `verify_failed` stays near zero and retention remains healthy.
