| Internet-Draft | Payment Discovery | April 2026 |
| Ryan, et al. | Expires 19 October 2026 | [Page] |
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.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 19 October 2026.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
This document may not be modified, and derivative works of it may not be created, except to format it for publication as an RFC or to translate it into languages other than English.¶
The "Payment" HTTP authentication scheme [I-D.httpauth-payment] 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 [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 [I-D.httpauth-payment] is always authoritative.¶
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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
Services that support discovery MUST publish an OpenAPI 3.x [OPENAPI] document that describes their API surface, including payment-enabled operations.¶
The OpenAPI document MUST be accessible at:¶
GET /openapi.json¶
The document MUST be served over HTTPS with
Content-Type: application/json.¶
The OpenAPI document MUST include the following standard fields:¶
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 Section 4.3.1). |
docs
|
object | OPTIONAL | Documentation and reference links (see Section 4.3.2). |
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:¶
communication, compute, data, developer-tools, media, search, social, storage, travel¶
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.¶
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 [LLMS-TXT]). |
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 [I-D.httpauth-payment].¶
Each payable operation MUST include a 402 response
in its responses object:¶
responses:
"402":
description: "Payment Required"
¶
This signals to clients that the operation may return a 402 challenge requiring payment.¶
Each operation SHOULD define its input schema using
the standard OpenAPI requestBody field:¶
requestBody:
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
required:
- prompt
¶
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.¶
Servers SHOULD include Cache-Control headers. A
maximum age of 5 minutes is RECOMMENDED for services
whose capabilities change infrequently:¶
Cache-Control: max-age=300¶
Clients SHOULD respect cache headers and refetch when capabilities may have changed.¶
{
"openapi": "3.1.0",
"info": {
"title": "Example AI API",
"version": "1.0.0"
},
"x-service-info": {
"categories": ["compute"],
"docs": {
"homepage": "https://api.example.com/docs",
"llms": "https://api.example.com/llms.txt",
"apiReference":
"https://api.example.com/reference"
}
},
"paths": {
"/v1/chat/completions": {
"post": {
"summary": "Chat completions",
"x-payment-info": {
"intent": "session",
"method": "tempo",
"amount": "500",
"currency":
"0x20c00000000000000000000000000000000000"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"model": { "type": "string" },
"messages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string"
},
"content": {
"type": "string"
}
},
"required": ["role",
"content"]
}
}
},
"required": ["model", "messages"]
}
}
}
},
"responses": {
"200": {
"description": "Successful response"
},
"402": {
"description": "Payment Required"
}
}
}
},
"/v1/embeddings": {
"post": {
"summary": "Text embeddings",
"x-payment-info": {
"intent": "charge",
"method": "tempo",
"amount": null,
"currency":
"0x20c00000000000000000000000000000000000",
"description": "Price varies by model
and token count."
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"model": { "type": "string" },
"input": { "type": "string" }
},
"required": ["model", "input"]
}
}
}
},
"responses": {
"200": {
"description": "Successful response"
},
"402": {
"description": "Payment Required"
}
}
}
}
}
}
¶
Discovery metadata is advisory. The 402 challenge defined in [I-D.httpauth-payment] 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.¶
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.¶
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.¶
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.¶
This document has no IANA actions.¶
This appendix provides informative guidance for building registries and aggregators on top of the discovery mechanism defined in this specification.¶
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 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 [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 Section 4.¶
The CoRE Resource Directory [RFC9176] defines push registration with leased lifetimes for constrained IoT devices. This specification uses crawl-based registration, which better suits HTTP services.¶
The A2A Protocol [A2A] uses
/.well-known/agent-card.json as a self-describing
service endpoint. This specification uses OpenAPI as
the discovery mechanism, providing richer schema
information.¶
The MCP Registry [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.¶
The x402 protocol [X402] uses HTTP 402 responses as the primary payment signal. This specification separates discovery (pre-request) from the payment challenge (at-request).¶
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 [ERC-8004] defines on-chain identity registries and domain verification. This specification operates entirely off-chain but is compatible with future on-chain anchoring.¶
The following JSON Schema defines the structure of
the x-payment-info OpenAPI extension. Tooling
authors SHOULD validate payment extensions against
this schema.¶
{
"$schema":
"https://json-schema.org/draft/2020-12/schema",
"title": "x-payment-info",
"type": "object",
"required": ["intent", "method", "amount"],
"properties": {
"intent": {
"type": "string",
"enum": ["charge", "session"]
},
"method": {
"type": "string"
},
"amount": {
"oneOf": [
{ "type": "null" },
{
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
}
]
},
"currency": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
¶
The following JSON Schema defines the structure of
the x-service-info OpenAPI extension.¶
{
"$schema":
"https://json-schema.org/draft/2020-12/schema",
"title": "x-service-info",
"type": "object",
"properties": {
"categories": {
"type": "array",
"items": { "type": "string" }
},
"docs": {
"type": "object",
"properties": {
"apiReference": {
"type": "string",
"format": "uri"
},
"homepage": {
"type": "string",
"format": "uri"
},
"llms": {
"type": "string",
"format": "uri"
}
}
}
}
}
¶
The authors thank the contributors to the MPP Registry reference implementation and the x402scan project, whose operational experience informed this specification.¶