# Discovery \[Let clients automatically discover your API's pricing]
## Overview
MPP's discovery system lets clients and agents learn what your endpoints cost before making a request. You serve a standard [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) document at `/openapi.json` with `x-payment-info` extensions that advertise one or more payment offers for each paid operation. Registries aggregate these documents so agents can find paid APIs automatically, and provide value-added services like reputation, search, and analytics.
:::info\[Discovery is advisory]
Discovery documents are informational hints. The runtime `402` Challenge remains the authoritative source of payment terms. Clients use discovery for display and planning, but defer to the Challenge for actual payment.
:::
## Registries
Registries aggregate discovery documents from multiple services, making it easy for clients and agents to find paid APIs.
| Registry | Description | How to add |
|----------|-------------|------------|
| [MPPScan](https://mppscan.com) | Public registry of MPP-enabled services with search and analytics | [Manually register](https://www.mppscan.com/register) in one click |
| [MPP Services directory](https://mpp.dev/services) | Curated list of live services on mpp.dev | [Submit a PR](https://github.com/tempoxyz/mpp) to add your service |
Agents can query the curated services directory over MCP at
`https://mpp.dev/mcp/services`. The server is read-only and exposes tools to
list services, rank services for an agent task, inspect endpoint offers, get
usage recipes, look up services by payment recipient, inspect available filters,
and fetch advisory OpenAPI summaries.
### Services MCP
The services MCP server is the agent-facing discovery surface for the curated
MPP directory:
```text
https://mpp.dev/mcp/services
```
Use it when an agent needs to:
* rank paid APIs by task, category, integration, or payment method
* turn a selected service into a usage recipe with endpoint candidates
* compare endpoint-level payment offers before constructing a request
* identify which services publish offers for a payment recipient from a `402`
Challenge
* inspect catalog facets before narrowing a search
* fetch a live OpenAPI summary or registry-derived endpoint view
```json
{
"mcpServers": {
"mpp-services": {
"url": "https://mpp.dev/mcp/services"
}
}
}
```
The MCP server is advisory and read-only. After discovery, clients call the
target service directly and treat the runtime `402` Challenge as authoritative.
For agent setup, MCP Inspector smoke tests, example prompts, and recipes, see
[Discover MPP services on Tempo docs](https://docs.tempo.xyz/guide/machine-payments/discover-services).
## Quick start
The `mppx` SDK generates discovery documents from your route configuration. Add `discovery()` to your server and it serves `/openapi.json` automatically.
```ts [server.ts]
import { Hono } from 'hono'
import { Mppx, discovery } from 'mppx/hono'
import { tempo } from 'mppx/server'
const app = new Hono()
const mppx = Mppx.create({
methods: [
tempo.charge({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0x...',
testnet: true,
}),
],
secretKey: process.env.MPP_SECRET_KEY,
})
app.get('/v1/fortune', mppx.charge({ amount: '0.01' }), (c) => c.json({ fortune: 'You will be rich' }))
// [!code hl:start]
discovery(app, mppx, {
auto: true,
info: { title: 'Fortune API', version: '1.0.0' },
})
// [!code hl:end]
```
This generates a `GET /openapi.json` endpoint with canonical `x-payment-info.offers[]` entries on each paid route.
### Express
```ts [server.ts]
import express from 'express'
import { Mppx, discovery } from 'mppx/express'
import { tempo } from 'mppx/server'
const app = express()
const mppx = Mppx.create({
methods: [
tempo.charge({
currency: '0x20c0000000000000000000000000000000000000',
recipient: '0x...',
testnet: true,
}),
],
secretKey: process.env.MPP_SECRET_KEY,
})
const pay = mppx.charge({ amount: '0.01' })
app.get('/v1/fortune', pay, (req, res) => res.json({ fortune: 'You will be rich' }))
// [!code hl:start]
discovery(app, mppx, {
info: { title: 'Fortune API', version: '1.0.0' },
routes: [{ handler: pay, method: 'get', path: '/v1/fortune' }],
})
// [!code hl:end]
```
### Next.js
In Next.js, `discovery()` returns a route handler you export from an API route.
```ts [app/openapi.json/route.ts]
import { discovery } from 'mppx/nextjs'
import { mppx, pay } from '../fortune/route'
// [!code hl:start]
export const GET = discovery(mppx, {
info: { title: 'Fortune API', version: '1.0.0' },
routes: [{ handler: pay, method: 'get', path: '/api/fortune' }],
})
// [!code hl:end]
```
## How it works
Your server exposes a `GET /openapi.json` endpoint that returns an OpenAPI document. Paid operations include an `x-payment-info` extension with one or more payment offers, and the document root can include `x-service-info` for service-level metadata.
```json [/openapi.json]
{
"openapi": "3.1.0",
"info": { "title": "My API", "version": "1.0.0" },
"x-service-info": {
"categories": ["ai"],
"docs": {
"homepage": "https://example.com",
"apiReference": "https://example.com/docs",
"llms": "/llms.txt"
}
},
"paths": {
"/v1/generate": {
"post": {
// [!code hl:start]
"x-payment-info": {
"offers": [
{
"amount": "1000000",
"currency": "0x20c0000000000000000000000000000000000001",
"description": "Generate text with Tempo",
"intent": "charge",
"method": "tempo"
},
{
"amount": "100",
"currency": "usd",
"description": "Generate text with Stripe",
"intent": "charge",
"method": "stripe"
}
]
},
// [!code hl:end]
"responses": {
"200": { "description": "Successful response" },
"402": { "description": "Payment Required" }
}
}
},
"/v1/models": {
"get": {
"responses": {
"200": { "description": "Successful response" }
}
}
}
}
}
```
### `x-payment-info`
Add this extension to any operation that requires payment. Prefer the canonical multi-offer shape:
| Field | Type | Description |
|-------|------|-------------|
| `offers` | `Offer[]` | Ordered list of payment offers the client can choose from |
### `offers[]`
| Field | Type | Description |
|-------|------|-------------|
| `amount` | `string \| null` | Payment amount in base units |
| `currency` | `string` | Currency code or token address |
| `description` | `string` | Human-readable description of the charge |
| `intent` | `string` | Payment intent (`charge` or `session`) |
| `method` | `string` | Payment method identifier (`tempo`, `stripe`) |
:::note\[Compatibility shorthand]
The flat single-offer form is still valid as shorthand for older emitters, but use it only for backward compatibility. New documents write the same data under `offers[]`.
```json [openapi.json]
{
// [!code hl:start]
"x-payment-info": {
"amount": "1000000",
"currency": "0x20c0000000000000000000000000000000000001",
"description": "Generate text with Tempo",
"intent": "charge",
"method": "tempo"
}
// [!code hl:end]
}
```
:::
### `x-service-info`
Optional root-level metadata about the service:
| Field | Type | Description |
|-------|------|-------------|
| `categories` | `string[]` | Free-form service categories (for example, `ai`, `payments`) |
| `docs.homepage` | `string` | Link to the service homepage |
| `docs.apiReference` | `string` | Link to API documentation |
| `docs.llms` | `string` | Link to an `llms.txt` file for AI consumption |
## Build manually
You can author a discovery document by hand following the [discovery specification](https://paymentauth.org/draft-payment-discovery-00.html). The document is a standard OpenAPI 3.1 file with two extensions:
::::steps
### Create the OpenAPI skeleton
Start with a standard OpenAPI 3.1 document:
```json [openapi.json]
{
"openapi": "3.1.0",
"info": {
"title": "My API",
"version": "1.0.0"
},
"paths": {}
}
```
### Add `x-payment-info` to paid operations
For each endpoint that requires payment, add the `x-payment-info` extension with an `offers` array. Add more objects to `offers[]` when the client can choose between alternative payment methods or currencies. Amounts are in base units (for example, `1000000` for $1.00 with 6 decimals).
```json [openapi.json]
{
"paths": {
"/v1/generate": {
"post": {
"summary": "Generate text",
// [!code hl:start]
"x-payment-info": {
"offers": [
{
"amount": "1000000",
"currency": "0x20c0000000000000000000000000000000000001",
"intent": "charge",
"method": "tempo"
}
]
},
// [!code hl:end]
"responses": {
"200": { "description": "Successful response" },
"402": { "description": "Payment Required" }
}
}
}
}
}
```
:::warning\[Include a 402 response]
Operations with `x-payment-info` must include a `402` response in the `responses` object. Validators flag this as an error if missing.
:::
### Add `x-service-info` (optional)
Add service-level metadata to the document root:
```json [openapi.json]
{
// [!code hl:start]
"x-service-info": {
"categories": ["ai", "text-generation"],
"docs": {
"homepage": "https://example.com",
"apiReference": "https://example.com/docs/api",
"llms": "https://example.com/llms.txt"
}
}
// [!code hl:end]
}
```
### Serve at `/openapi.json`
Serve the document at `GET /openapi.json` with appropriate caching:
```http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=300
```
::::
## CLI
Generate a static discovery document from a config module:
```bash [terminal]
$ npx mppx discover generate ./discovery.config.ts
```
Validate an existing discovery document from a file or URL:
```bash [terminal]
$ npx mppx discover validate https://example.com/openapi.json
```
## Validation
Common validation issues:
| Issue | Severity | Description |
|-------|----------|-------------|
| Missing `402` response | Error | Operations with `x-payment-info` must include a `402` response |
| Invalid amount format | Error | Each `offers[].amount` value must be a non-negative integer string |
| Missing `requestBody` | Warning | `POST`/`PUT`/`PATCH` operations without a `requestBody` definition |
| Invalid URI in docs | Error | `docs` links must be valid URIs or absolute paths |
## Specification