Discovery Spec

How to make your MPP server discoverable by agents. Publish an OpenAPI document, return proper 402 challenges, and validate with our CLI.

Why This Matters

If agents can't discover your API, they can't call it. Discovery turns your endpoint from merely deployed to reliably invocable. When your OpenAPI metadata and runtime 402 behavior agree, agents succeed on the first pass — fewer failures, less debugging, more real traffic.

•Publish an OpenAPI document at /openapi.json as the canonical machine-readable contract.

•Treat runtime 402 challenge behavior as the final source of truth.

•Validate with @suimpp/discovery before registering.

OpenAPI Document

Your server must serve an OpenAPI 3.x document at GET /openapi.json. This is how agents and the suimpp registry discover your endpoints and pricing.

Required fields

Field	Location	Purpose
openapi	Root	Must be "3.0.x" or "3.1.x"
info.title	Root	Human-readable server name
info.version	Root	API version string
info.x-guidance	Root	Agent instructions — how to use your API
x-payment-info	Per operation	Pricing and protocol info (see below)
responses.402	Per operation	Declares that endpoint requires payment
requestBody.schema	Per operation	Input schema for agent invocation
responses.200.schema	Per operation	Output schema for agent parsing

Minimal valid example

/openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "My API",
    "version": "1.0.0",
    "description": "Example MPP-enabled server",
    "x-guidance": "Use POST /api/search for neural web search. Accepts a JSON body with a 'query' field."
  },
  "paths": {
    "/api/search": {
      "post": {
        "operationId": "search",
        "summary": "Neural web search",
        "x-payment-info": {
          "pricingMode": "fixed",
          "price": "0.010000",
          "protocols": ["mpp"]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": { "type": "string", "minLength": 1 }
                },
                "required": ["query"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment Required" }
        }
      }
    }
  }
}

x-payment-info

Every paid operation must include an x-payment-info object. This tells agents the pricing model and which payment protocols are accepted.

Field	Required	Description
protocols	Yes	Array of accepted protocols, e.g. ["mpp"]
pricingMode	Yes	"fixed", "range", or "quote"
price	If fixed	Exact price as string (e.g. "0.010000")
minPrice	If range	Minimum price for range pricing
maxPrice	If range	Maximum price for range pricing

Pricing modes

// Fixed pricing — most common
"x-payment-info": {
  "pricingMode": "fixed",
  "price": "0.010000",
  "protocols": ["mpp"]
}

// Range pricing — server decides within bounds
"x-payment-info": {
  "pricingMode": "range",
  "minPrice": "0.005000",
  "maxPrice": "0.050000",
  "protocols": ["mpp"]
}

// Quote pricing — price set at request time
"x-payment-info": {
  "pricingMode": "quote",
  "protocols": ["mpp"]
}

Important

For fixed pricing, use price (not "amount"). The 402 challenge uses amount, but the OpenAPI spec uses price.

402 Challenge Behavior

When a client calls a paid endpoint without credentials, your server must return HTTP 402 with a WWW-Authenticate header:

Response

HTTP/1.1 402 Payment Required
WWW-Authenticate: MPP method="sui",
  amount="0.01",
  currency="0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
  recipient="0xYOUR_SUI_ADDRESS"

•method="sui" — identifies the Sui charge method

•amount — human-readable USDC amount (e.g. "0.01" = 1 cent)

•currency — fully qualified USDC coin type on Sui

•recipient — your Sui address (0x-prefixed, 64 hex chars)

The validator probes your first payable endpoint, expects a 402, and verifies the header matches your OpenAPI metadata. This is the final source of truth.

Request & Response Schemas

Each payable operation should define input and output schemas. Without them, agents can't construct requests or parse responses reliably.

•Input schema: Define requestBody.content["application/json"].schema with typed properties and required fields.

•Output schema: Define responses.200.content["application/json"].schema so agents know what to expect.

•Guidance: Add info.x-guidance at the top level to explain how an agent should use your API at a high level.

Missing schemas produce warnings during validation. They won't block registration but will hurt discoverability and agent success rates.

Validate Before Registering

Use the @suimpp/discovery CLI to check your server before registering:

Terminal

npx @suimpp/discovery check https://mpp.example.com

Output

✓ OpenAPI document found at /openapi.json
✓ 12 payable endpoints detected
✓ 402 challenge response verified
✓ Sui USDC payment method detected
✓ Recipient: 0x76d7...5012
0 errors, 0 warnings

The validator runs two phases:

1
OpenAPI Discovery
Fetches /openapi.json, validates structure, extracts endpoints with x-payment-info.
2
Endpoint Probe
Sends a request to the first payable endpoint, expects 402, verifiesWWW-Authenticate header has method=sui, valid USDC type, and valid recipient.

Common Errors

Error	Cause	Fix
Not Found	No document at /openapi.json	Serve your OpenAPI doc at the root path
No payable endpoints	Missing x-payment-info	Add x-payment-info to each paid operation
No 402 response	Endpoint doesn't return 402	Return 402 with WWW-Authenticate for unauthenticated requests
WWW-Authenticate missing	Header not set on 402	Add WWW-Authenticate with method, amount, currency, recipient
Invalid recipient	Malformed Sui address	Use a valid 0x-prefixed, 64 hex char address
Schema missing	No requestBody or response schema	Add typed schemas for agent compatibility

Discovery Precedence

suimpp uses two sources to verify your server. Both must agree:

Priority	Source	Location
1	OpenAPI document	/openapi.json
2	402 API response	WWW-Authenticate header

Ready to register?

Once your server passes validation, register it on suimpp.dev to appear in the server catalog and start tracking payments automatically.

→Sui Charge Method Spec →Register your server →Developer guide →GitHub