mpp-service-discovery

MPP Service Discovery

Before writing code

Fetch live docs:

1. Fetch https://paymentauth.org/draft-payment-discovery-00.html for the canonical service discovery specification
2. Web-search mpp service discovery openapi x-payment-info llms.txt for implementation examples
3. Web-search site:mpp.dev directory for the MPP payments directory and listing requirements
4. Fetch https://mpp.dev/overview for discovery-related documentation

Conceptual Architecture

What Service Discovery Does

MPP service discovery allows AI agents to autonomously find, understand, and pay for HTTP services. It uses two mechanisms:

1. OpenAPI Document — Machine-readable API spec with payment extensions
2. llms.txt — Human/AI-readable service description for LLM agent discovery

OpenAPI Document (GET /openapi.json)

Services publish an OpenAPI 3.x document with two custom extensions:

x-service-info (Top-Level)

{
  "openapi": "3.0.0",
  "info": { "title": "My Paid API", "version": "1.0.0" },
  "x-service-info": {
    "categories": ["compute", "data", "media"],
    "docs": {
      "apiReference": "https://api.example.com/docs",
      "homepage": "https://example.com",
      "llms": "https://api.example.com/llms.txt"
    }
  }
}

x-payment-info (Per-Operation)

{
  "paths": {
    "/api/data": {
      "get": {
        "summary": "Get premium data",
        "x-payment-info": {
          "intent": "charge",
          "method": "tempo",
          "amount": "100",
          "currency": "0x20C000000000000000000000b9537d11c60E8b50",
          "description": "$0.01 per request"
        },
        "responses": {
          "200": { "description": "Premium data" },
          "402": { "description": "Payment required" }
        }
      }
    }
  }
}

x-payment-info Fields

Field	Required	Description
intent	Yes	"charge" or "session"
method	Yes	Payment method (e.g., "tempo", "stripe")
amount	No	Price (null for dynamic pricing)
currency	Yes	Currency identifier (contract address for crypto, code for fiat)
description	No	Human-readable pricing description

Discovery Properties

• amount can be null for dynamic pricing — the 402 challenge remains authoritative
• Discovery data is advisory only — agents should still handle the actual 402 challenge
• Servers should include Cache-Control: max-age=300
• Size limit: 64 KB per OpenAPI document
• Registries recrawl every 24 hours minimum
• Services are delisted after 7+ consecutive crawl failures

llms.txt

A text file (analogous to robots.txt) describing the service for autonomous agents:

# My Paid API
> AI-powered data analysis service

## Endpoints
- GET /api/analyze — Analyze data ($0.05/request, Tempo USDC)
- GET /api/summarize — Summarize text ($0.02/request, Tempo USDC)

## Pricing
All prices in USDC. Volume discounts available via session payments.

## Authentication
Payments via MPP (HTTP 402). No API key required.

## Contact
support@example.com

MPP Payments Directory

Services can be listed in the MPP payments directory (100+ services):

• Categories: model providers, developer tools, compute, data vendors
• Listing requires a valid OpenAPI document with x-payment-info
• Directory recrawls services periodically

Implementation Pattern

app.get('/openapi.json', (c) => {
  return c.json({
    openapi: '3.0.0',
    info: { title: 'My API', version: '1.0.0' },
    'x-service-info': {
      categories: ['data'],
      docs: { llms: 'https://api.example.com/llms.txt' },
    },
    paths: {
      '/api/data': {
        get: {
          summary: 'Get data',
          'x-payment-info': {
            intent: 'charge',
            method: 'tempo',
            amount: '100',
            currency: '0x20C000000000000000000000b9537d11c60E8b50',
            description: '$0.01 per request',
          },
          responses: {
            '200': { description: 'Data returned' },
            '402': { description: 'Payment required' },
          },
        },
      },
    },
  });
});

app.get('/llms.txt', (c) => {
  return c.text(`# My API\n> Premium data service\n\n## Endpoints\n...`);
});

Best Practices

• Include both openapi.json and llms.txt for maximum discoverability
• Keep the OpenAPI document under 64 KB
• Set Cache-Control: max-age=300 on discovery endpoints
• Include all payable operations with 402 responses declared
• Use descriptive description fields for human-readable pricing
• Update discovery documents when pricing changes
• Register with the MPP payments directory for broader visibility

Fetch the latest service discovery specification from paymentauth.org for exact extension schemas, directory listing requirements, and llms.txt format before implementing.