---
title: "Payment Discovery Extension"
type: concept
tags: [discovery, extensions, emerging]
created: 2026-08-10
updated: 2026-08-10
sources: ["raw/github_doc-specs-extensions-draft-payment-discovery-00-md.md"]
confidence: high
mpp_snapshot: "2026-08-10"
---

## Definition

`draft-payment-discovery-00` defines an **optional** service-discovery framework layered on top of the [[concepts/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)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `categories` | array of strings | OPTIONAL | Free-form service categories. RECOMMENDED starting vocabulary: `communication, compute, data, developer-tools, media, search, social, storage, travel`. Lowercase, hyphenated, concise; registries SHOULD cap at 5 categories; clients SHOULD ignore unrecognized values. |
| `docs` | object | OPTIONAL | `apiReference` (URI), `homepage` (URI), `llms` (URI — LLM-friendly docs per the llms.txt proposal). All URIs conform to RFC 3986. |

### `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:**

| 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` = dynamic/variable pricing. When non-null: ASCII-digit string, non-negative integer, no leading zeros except `"0"` itself — consistent with the `amount` field in the core spec's request object |
| `currency` | string | OPTIONAL | Token contract address (blockchain methods) or ISO 4217 code (fiat) |
| `description` | string | OPTIONAL | Human-readable pricing note |

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 [[concepts/payment-http-auth-scheme|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 [[concepts/payment-http-auth-scheme|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

- [[concepts/payment-http-auth-scheme]] — the runtime 402 challenge/credential mechanism that discovery is always subordinate to
- [[concepts/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
- [[concepts/mpp-overview]] — situates Discovery as one of the optional "Extensions" in the four-layer architecture
- [[concepts/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)