---
name: mpp-service-discovery-0cd8c0005f30
description: >
  Implement MPP service discovery — OpenAPI documents with x-payment-info
  extensions, x-service-info metadata, and llms.txt for autonomous agent
  discovery. Use when publishing paid API metadata for AI agents to find and pay
  for your services.
---

# MPP Service Discovery

## Before writing code

**Fetch live docs**:
1. Fetch `https://paymentauth.org/` 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)

```json
{
  "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)

```json
{
  "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

```typescript
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.


---
Source attribution: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/stripe-mpp/skills/mpp-service-discovery/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/stripe-mpp/skills/mpp-service-discovery/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, ML / AI Engineer, Product Manager
Specialties: API, Backend
Tools: Paymentauth
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: c090e4baf69834d9a2e5080b625f0092d3505818fa5c3860d3c60e3e78b8376a