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.