]> Tempo Labs

brendan@tempo.xyz

Tempo Labs

jake@tempo.xyz

Merit Systems

ryan@merit.systems

Merit Systems

sam@merit.systems

This document defines a service discovery framework for the "Payment" HTTP authentication scheme. Services publish an OpenAPI document annotated with payment extensions that describe pricing, payment methods, and intent types. The OpenAPI document serves as the canonical machine-readable contract, providing payment metadata and, when declared, input and output schemas so that agents can discover and invoke endpoints. The runtime 402 challenge remains authoritative for all payment parameters.

Introduction The "Payment" HTTP authentication scheme enables servers to require payment for resource access using the HTTP 402 status code. While the 402 challenge provides all information needed to complete a single paid exchange, clients and agents benefit from discovering payment-enabled services before initiating requests. This specification defines a discovery mechanism based on OpenAPI . Services publish an OpenAPI document annotated with two extensions: x-service-info: Top-level service metadata including categories and documentation links. x-payment-info: Per-operation payment requirements including one or more payment offers. OpenAPI provides payment metadata and can provide input and output schemas, enabling agents to discover and invoke endpoints without additional documentation. Discovery is OPTIONAL. Servers MAY implement this mechanism to improve client experience. Clients MUST NOT require discovery to function; the 402 challenge in is always authoritative.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology

Service

An HTTP origin that accepts payment via the "Payment" authentication scheme.

Payable Operation

An API operation that requires payment, indicated by a 402 response and x-payment-info extension in the OpenAPI document.

Payment Offer

A discovered payment alternative for a payable operation. Multiple payment offers correspond to alternative runtime Payment challenges for the same operation.

OpenAPI Discovery Services that support discovery MUST publish an OpenAPI 3.x document that describes their API surface, including payment-enabled operations.

Document Location The OpenAPI document MUST be accessible at:

The document MUST be served over HTTPS with Content-Type: application/json.

Required Top-Level Fields The OpenAPI document MUST include the following standard fields: openapi: The OpenAPI version (e.g., "3.1.0"). info.title: The service name. info.version: The API version. paths: At least one path with operations.

Service Extension: x-service-info The OpenAPI document MAY include a top-level x-service-info extension object to provide service metadata that is not part of the standard OpenAPI specification. Field Type Required Description categories array OPTIONAL Service categories (see ). docs object OPTIONAL Documentation and reference links (see ).

Categories The categories field, when present, MUST be an array of strings. Category values are free-form; services MAY use any string value. The following values are RECOMMENDED as a starting vocabulary:

Category values SHOULD be lowercase, use hyphens for multi-word values, and be concise. Registries SHOULD limit services to no more than 5 categories. Clients SHOULD ignore category values they do not recognize.

Documentation Links The docs field, when present, MUST be a JSON object with the following optional fields: Field Type Description apiReference string (URI) API reference documentation URL. homepage string (URI) Main documentation or landing page. llms string (URI) LLM-friendly documentation URL (see ). All URI values MUST conform to .

Payment Extension: x-payment-info Each payable operation MUST include the x-payment-info extension object on the operation. This extension describes one or more payment offers for the operation. The extension supports two equivalent forms: Single-offer shorthand: an object containing the fields of a single payment offer directly. Multi-offer form: an object containing an offers array of one or more payment offer objects. Servers publishing new discovery documents SHOULD use the multi-offer form. Clients and registries MUST accept both forms. When the single-offer shorthand is used, clients and registries MUST treat it as equivalent to a multi-offer form containing exactly one payment offer. When multiple offers are present, clients SHOULD treat them as alternative ways to access the same operation. At runtime, the client selects one offer and fulfills the corresponding 402 challenge.

Payment Offer Object Field Type Required Description intent string REQUIRED "charge" (per-request) or "session" (pay-as-you-go). method string REQUIRED Payment method identifier (e.g., "tempo", "stripe"). amount string or null REQUIRED Cost in base currency units. null indicates dynamic pricing. currency string OPTIONAL Currency identifier. For blockchain methods: token contract address. For fiat: ISO 4217 code. description string OPTIONAL Human-readable pricing note. The amount field is REQUIRED but its value MAY be null to support offers where pricing depends on request parameters (e.g., variable-cost operations). When non-null, the value MUST be a string of ASCII digits (0-9) representing a non-negative integer in the smallest denomination of the currency (e.g., cents for USD, wei for ETH). Leading zeros MUST NOT be used except for the value "0". This format is consistent with the amount field defined in the request object of .

Payment Offer Examples The following examples illustrate common multi-offer patterns.

Same Intent, Different Currency The same charge intent can be offered in multiple currencies for the same operation:

Multiple Methods Under One Intent The same charge intent can be offered through different payment methods:

Fixed and Dynamic Offers An operation can mix fixed-price and dynamic-price offers in the same intent set. In this example, Tempo is fixed-price while Stripe is dynamic:

Multiple Methods and Intents An operation can advertise multiple methods and multiple intents at the same time:

402 Response Declaration Each payable operation MUST include a 402 response in its responses object:

This signals to clients that the operation may return a 402 challenge requiring payment.

Input Schema Each operation SHOULD define its input schema using the standard OpenAPI requestBody field:

Input schemas enable agents to construct valid requests without additional documentation. Operations that omit input schemas MAY be marked as "schema-missing" by discovery clients and registries.

Output Schema This section reiterates existing OpenAPI response and schema semantics for payable operations. It defines no new output-schema extension or schema dialect. The guidance appears here because successful response shape is useful to evaluate before payment. Each payable operation SHOULD describe every successful response representation it intends to return using the standard OpenAPI responses object. Each JSON response representation SHOULD include a schema member under its actual media type. A schema attached to one response status and media type describes only that representation. It does not describe other success statuses or media types. A client MUST NOT treat a schema for one successful representation as an operation-wide guarantee unless every successful representation declared by the OpenAPI document entails the same guarantee.

Output schemas enable agents to evaluate seller-declared response shapes before invoking an operation. Operations that omit every successful response schema MAY be marked "output-schema-missing" by discovery clients and registries. A document with schemas for only some successful representations does not provide an operation-wide output guarantee. The following MUST NOT be treated as requiredness guarantees: the OpenAPI example or examples fields the schema default field property presence in an example object a property listed in properties but omitted from required GraphQL selection sets that are not represented in the OpenAPI document Schema interpretation MUST follow the OpenAPI version and JSON Schema dialect declared by the document. A required property name alone does not establish that the enclosing instance is an object or that the value is non-null. A client MUST NOT claim that a response path is always present and non-null unless every applicable success status, media type, and valid schema branch entails that claim, including applicable type, composition, reference, and array-cardinality semantics. A client that cannot evaluate the declared dialect or resolve relevant schema semantics SHOULD fail closed. Any projected output guarantee remains seller-declared discovery metadata. It MUST NOT be described as a runtime observation or runtime validation. Payable operations still MUST include a 402 response as specified in . Output schemas are not payment terms. Presence or absence of an output schema MUST NOT change whether an operation is payable.

Caching Servers SHOULD include Cache-Control headers. A maximum age of 5 minutes is RECOMMENDED for services whose capabilities change infrequently:

Clients SHOULD respect cache headers and refetch when capabilities may have changed.

Example OpenAPI Document

Relationship to the 402 Challenge Discovery metadata is advisory. The 402 challenge defined in is always authoritative. Specifically: If discovery indicates payment offer details that differ from the 402 challenge, including method, intent, amount, or currency, the 402 challenge takes precedence. Clients MUST NOT cache discovery data as a substitute for processing 402 challenges. Output schemas describe successful JSON payloads for evaluation before a request. They are not payment terms and do not replace the runtime 402 challenge or the actual HTTP response. Discovery exists to help clients and agents find and evaluate services before making requests, not to replace the runtime payment negotiation defined by the core protocol.

Security Considerations

Discovery Spoofing Discovery information is not cryptographically authenticated beyond HTTPS transport security. Clients MUST NOT rely on discovery metadata for security decisions. The 402 challenge is authoritative for all payment parameters.

Information Disclosure OpenAPI documents reveal payment capabilities, endpoint structure, input schemas, output schemas, and pricing to unauthenticated clients. Service operators SHOULD consider whether this disclosure is acceptable for their use case.

Cross-Origin Requests Browser-based clients may need to access discovery endpoints cross-origin. Servers that intend to support browser-based clients SHOULD include appropriate CORS headers on OpenAPI document responses.

IANA Considerations This document has no IANA actions.

&RFC2119; &RFC3986; &RFC8174; &RFC8259; &RFC9110; OpenAPI Initiative &RFC9176; Google Anthropic Coinbase

Changes from draft-payment-discovery-00 This revision adds an Output Schema section parallel to Input Schema. It scopes output claims to every applicable success status, media type, and schema branch, and distinguishes seller-declared schema evidence from runtime validation. The example OpenAPI document includes one JSON 200 schema and keeps a second paid operation description-only. Information Disclosure now covers output schemas. Payment challenges remain authoritative. No payment method, intent, amount, currency, or settlement behavior is specified or changed.

Registry and Aggregator Guidance This appendix provides informative guidance for building registries and aggregators on top of the discovery mechanism defined in this specification.

Registries A registry is a server that discovers, validates, and indexes payment-enabled services into a searchable catalog. Registries MAY discover services by: Crawling OpenAPI documents from submitted domains. Accepting domain submissions from service operators. Consuming snapshots from other registries. If a domain serves a valid OpenAPI document with x-payment-info extensions over HTTPS, that constitutes sufficient proof of domain ownership. Registries SHOULD re-crawl services periodically (at least every 24 hours is RECOMMENDED). If the discovery document becomes invalid or unreachable, the registry SHOULD delist the service after 7 or more consecutive failures. Registries SHOULD enforce crawl constraints: HTTPS only, 10-second timeouts, 64 KB size limits, and rate limiting.

Aggregators Aggregators consume registry data and layer on their own views: curating (filtering by quality or vertical), enriching (adding trust scores, uptime, volume data), reshaping (exposing agent-native formats such as llms.txt ), or federating (merging data from multiple registries). Aggregators are not required to use the registry API schema. The only universal contract is the OpenAPI discovery mechanism defined in .

Comparison with Prior Art

CoRE Resource Directory (RFC 9176) The CoRE Resource Directory defines push registration with leased lifetimes for constrained IoT devices. This specification uses crawl-based registration, which better suits HTTP services.

Agent2Agent Protocol (A2A) The A2A Protocol uses /.well-known/agent-card.json as a self-describing service endpoint. This specification uses OpenAPI as the discovery mechanism, providing richer schema information.

MCP Registry The MCP Registry implements a three-layer architecture with reverse-DNS namespacing and SHA-256 package integrity. This specification uses domain authority rather than OAuth-based registration.

x402 Protocol The x402 protocol uses HTTP 402 responses as the primary payment signal. This specification separates discovery (pre-request) from the payment challenge (at-request).

OpenAPI-First Discovery (x402scan) The x402scan project uses OpenAPI documents as the canonical discovery signal, with /.well-known/x402 as a fallback. This specification adopts the same OpenAPI-first approach, using x-payment-info as the payment extension with fields consistent with the Payment authentication scheme.

ERC-8004 (Trustless Agents) ERC-8004 defines on-chain identity registries and domain verification. This specification operates entirely off-chain but is compatible with future on-chain anchoring.

JSON Schema for x-payment-info The following JSON Schema defines the structure of the x-payment-info OpenAPI extension. Tooling authors SHOULD validate payment extensions against this schema.

JSON Schema for x-service-info The following JSON Schema defines the structure of the x-service-info OpenAPI extension.

Acknowledgments The authors thank the contributors to the MPP Registry reference implementation and the x402scan project, whose operational experience informed this specification.