Directory entry or live challenge: what should an x402 buyer trust?
Guides
Use a directory to discover services, then verify the current method, availability and payment terms at the origin before authorizing payment.
An API directory helps an agent find a service, but its entry can be a delayed snapshot. A current origin response determines whether a route is available now and which payment terms the server is actually offering. Treat discovery and purchase authorization as two separate steps.
First compare the directory route and HTTP method with the current service specification. A POST resource cannot safely be called as GET merely because an older index says so. Confirm the exact URL, required input and response format in the origin OpenAPI document or another current operator source.
Then make an unpaid request according to the documented contract. A live HTTP 402 response carries the current x402 payment requirements. Check protocol version, network, scheme, asset, amount, recipient, timeout and resource before signing. Reject any mismatch with the task or the client budget.
A service can remain visible in a directory after the operator has paused it. HTTP 503 without a payment challenge means the resource is currently unavailable before payment; do not manufacture a payment payload or fall back to an old directory price. Read the current service status and retry only when the operator reports a usable state.
Record provenance for every decision: directory URL and observation time, origin specification version, status timestamp and the particular payment requirement. This makes a later discrepancy explainable and prevents cached discovery metadata from being presented as a current offer.
If directory and origin disagree, use the directory as a lead and the origin as the operational source for that request. Report the stale entry to the operator or directory maintainer. After an ambiguous paid response, reconcile the existing settlement and delivery evidence before creating another authorization.