]> 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 both payment metadata and input 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 intent type, payment method, amount, and currency. OpenAPI provides both payment metadata and input 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.

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 the payment requirements for the operation. 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 endpoints 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 .

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.

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 a payment method that differs from the 402 challenge, the 402 challenge takes precedence. If discovery indicates an amount that differs from the 402 challenge, the 402 challenge takes precedence. Clients MUST NOT cache discovery data as a substitute for processing 402 challenges. 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, 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

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.