wikis / Machine Payments Protocol (MPP) / wiki / concepts / payment-discovery.md view as markdown report a mistake

Definition

draft-payment-discovery-00 defines an optional service-discovery framework layered on top of the payment http auth scheme. Services publish an OpenAPI 3.x document annotated with two payment-specific extensions — x-service-info (service metadata) and x-payment-info (per-operation payment offers) — so that a client or agent can find and evaluate payment-enabled endpoints, and construct valid requests, before ever making an HTTP call. The OpenAPI document is the canonical machine-readable contract for both pricing metadata and input schemas. Discovery is explicitly advisory: the runtime 402 challenge is always authoritative for the actual payment parameters.

How It Works

Publishing the document

A discovering service MUST publish an OpenAPI 3.x document at GET /openapi.json, served over HTTPS with Content-Type: application/json. Required top-level OpenAPI fields: openapi (version string, e.g. "3.1.0"), info.title, info.version, and paths (at least one path with operations).

x-service-info (top-level, optional)

x-payment-info (per operation, required on every payable operation)

Each Payable Operation (one that can return 402) MUST carry x-payment-info describing one or more Payment Offers — alternative runtime challenges the operation may issue. Two equivalent forms:

• Single-offer shorthand: an object with the offer's fields directly.
• Multi-offer form: an object with an offers array of offer objects. Servers publishing new documents SHOULD use this form; clients/registries MUST accept both and MUST treat shorthand as a one-element offers array.

Payment Offer object:

Note: discovery's offer intent enum is ["charge", "session"] — the discovery spec does not itself list subscription as an offerable intent value, though the JSON Schema does not forbid other registered intent strings appearing in practice; charge and session are the two values shown throughout.

When multiple offers appear, clients treat them as alternative ways to reach the same operation — pick one at runtime and fulfill its corresponding 402 challenge. Example patterns shown in the spec: same intent priced in different currencies; the same intent offered via different methods; a mix of fixed-price and dynamic (amount: null) offers side by side; and an operation advertising multiple methods and multiple intents (e.g. session/tempo and charge/tempo and charge/stripe) simultaneously.

402 response declaration and input schema

Each payable operation MUST declare a 402 entry in its OpenAPI responses object (e.g. description: "Payment Required"), signaling that the operation may 402. Operations SHOULD also define their input schema via the standard OpenAPI requestBody field, so agents can construct valid calls without extra documentation; operations that omit input schemas MAY be flagged "schema-missing" by discovery clients/registries.

Caching

Servers SHOULD send Cache-Control headers on the discovery document; a max age of 5 minutes (Cache-Control: max-age=300) is RECOMMENDED for services whose capabilities change infrequently. Clients SHOULD respect these headers and refetch when capabilities may have changed.

Relationship to the runtime 402 challenge

Discovery metadata is advisory only. If discovery-advertised offer details (method, intent, amount, or currency) differ from the actual runtime 402 challenge, the 402 challenge takes precedence. Clients MUST NOT cache discovery data as a substitute for processing the live 402 challenge. Discovery exists to help clients/agents find and evaluate services beforehand, not to replace runtime payment negotiation.

Registries and aggregators (informative appendix)

A registry discovers, validates, and indexes payment-enabled services (crawling submitted domains, accepting submissions, or consuming other registries' snapshots); a valid OpenAPI document with x-payment-info served over HTTPS is treated as sufficient proof of domain ownership. Registries SHOULD re-crawl at least every 24 hours and SHOULD delist after 7+ consecutive crawl failures; SHOULD enforce HTTPS-only, 10-second timeouts, 64KB size limits, and rate limiting. Aggregators consume registry data and layer curation, enrichment (trust/uptime/volume scores), reshaping (e.g. into llms.txt), or federation across registries — the only universal contract is the OpenAPI discovery mechanism itself.

Key Parameters

• Discovery document location: GET /openapi.json (HTTPS, Content-Type: application/json)
• x-service-info.categories, x-service-info.docs.{apiReference,homepage,llms}
• x-payment-info offer fields: intent (charge|session), method, amount (string|null), currency, description
• 402 declared in responses."402"
• Cache-Control: max-age=300 recommended

When To Use

Use payment discovery when you want clients or agents to be able to browse, compare, and pre-select among payment-enabled services or operations before making the first paid call — e.g., an agent shopping across multiple compute providers by price, or a registry/aggregator (à la x402scan) building a searchable catalog of payable APIs. It is entirely optional per the core protocol: a server can support MPP payments with no discovery document at all, and a client can always fall back to hitting the endpoint directly and reading the live 402 challenge.

Risks & Pitfalls

• Discovery spoofing / no cryptographic authentication: discovery info is only as trustworthy as HTTPS transport security — it is not otherwise authenticated. Clients MUST NOT make security decisions based on discovery metadata; the 402 challenge is authoritative for all payment parameters.
• Information disclosure: publishing /openapi.json reveals payment capabilities, endpoint structure, input schemas, and pricing to any unauthenticated client — operators should weigh whether that disclosure is acceptable.
• Cross-origin access: browser-based clients may need the discovery endpoint reachable cross-origin; servers intending to support them SHOULD add CORS headers.
• Staleness: clients that over-cache discovery data (beyond the server's Cache-Control) risk acting on stale pricing/offer data that the live 402 challenge will simply override — better to treat discovery purely as a planning aid.

Related Concepts

• payment http auth scheme — the runtime 402 challenge/credential mechanism that discovery is always subordinate to
• payment intents — the charge intent (and session, referenced here as an offerable intent though not one of the two intent specs curated in this KB) that discovery offers describe
• mpp overview — situates Discovery as one of the optional "Extensions" in the four-layer architecture
• mcp transport — a separate mechanism (capability advertisement) for signaling payment support within an MCP/JSON-RPC session, rather than via OpenAPI

Sources

• raw/github_doc-specs-extensions-draft-payment-discovery-00-md.md (specs/extensions/draft-payment-discovery-00.md — Service Discovery for HTTP Payment Authentication)