{"openapi":"3.0.0","info":{"title":"MCPay Gateway","version":"1.0.0","description":"Per-call payment gateway for AI agents on MultiversX Supernova.\n\nThree auth modes, all documented machine-readably:\n  • Easy Mode — send `x-mcpay-key: <api_key>` (or `Authorization: Bearer`) to charge a pre-paid owner balance.\n  • Pro Mode x402 — no signup. Hit any /mcp/:slug/:tool → receive 402 challenge → pay on-chain → retry with `x-payment: base64(envelope)`.\n  • OAuth 2.1 + DCR — self-register at /oauth/register, exchange at /oauth/token, use Bearer header.\n\nStart at GET /api/catalog. Full x402 profile (challenge + envelope JSON Schema) at /.well-known/x402.json."},"servers":[{"url":"https://testnet.mcpay.network","description":"testnet gateway"}],"paths":{"/health":{"get":{"summary":"Liveness probe — returns {ok, network, chainId, commit?}.","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"network":{"type":"string"},"chainId":{"type":"string"}}}}}}}}},"/api/catalog":{"get":{"summary":"List all paid MCP servers on this gateway.","responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"type":"object","required":["items","count","network"],"properties":{"network":{"type":"string"},"chainId":{"type":"string"},"count":{"type":"integer"},"items":{"type":"array","items":{"type":"object","required":["id","slug","name","category","priceUsd","toolCount"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"tagline":{"type":"string"},"priceUsd":{"type":"number","description":"Per-call price in USD."},"toolCount":{"type":"integer"},"verified":{"type":"boolean"},"featured":{"type":"boolean"},"acceptedTokens":{"type":"array","items":{"type":"string"}},"provider":{"type":"object","properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"badge":{"type":"string","enum":["new","active","trusted","verified"]}}},"stats":{"type":"object","properties":{"calls7d":{"type":"integer"},"avgLatencyMs":{"type":"integer"},"uptimePct":{"type":"number"},"refundRatePct":{"type":"number"}}}}}}}}}}}}}},"/api/mcps/{slug}":{"get":{"summary":"Single MCP detail with tools + SLA + pricing.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"MCP detail","content":{"application/json":{"schema":{"type":"object","required":["id","slug","name","category","priceUsd","toolCount"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"tagline":{"type":"string"},"priceUsd":{"type":"number","description":"Per-call price in USD."},"toolCount":{"type":"integer"},"verified":{"type":"boolean"},"featured":{"type":"boolean"},"acceptedTokens":{"type":"array","items":{"type":"string"}},"provider":{"type":"object","properties":{"slug":{"type":"string"},"displayName":{"type":"string"},"badge":{"type":"string","enum":["new","active","trusted","verified"]}}},"stats":{"type":"object","properties":{"calls7d":{"type":"integer"},"avgLatencyMs":{"type":"integer"},"uptimePct":{"type":"number"},"refundRatePct":{"type":"number"}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine code."},"hint":{"type":"string","description":"Human-readable recovery hint."}}}}}}}}},"/mcp/{slug}/.card":{"get":{"summary":"Machine-readable MCP server card (tools, pricing, auth schemes, accepted tokens).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Card","content":{"application/json":{}}},"404":{"description":"Not found"}}}},"/mcp/{slug}/{tool}":{"post":{"summary":"Invoke an MCP tool. Unauthenticated call → 402 with an x402 challenge; pay on-chain and retry with x-payment header, OR send x-mcpay-key for Easy Mode.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"tool","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-mcpay-key","in":"header","required":false,"schema":{"type":"string"},"description":"Easy Mode API key. Omit for Pro Mode (x402)."},{"name":"x-payment","in":"header","required":false,"schema":{"type":"string"},"description":"Base64(JSON) of {tx_hash, nonce, from} envelope after paying the 402 challenge. See /.well-known/x402.json for schema."}],"requestBody":{"description":"Tool-specific input. Shape is declared in the MCP card (/mcp/:slug/.card).","required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Tool result","content":{"application/json":{"schema":{"type":"object","required":["ok","tool","data","meta"],"properties":{"ok":{"const":true},"tool":{"type":"string"},"data":{},"meta":{"type":"object","properties":{"call_id":{"type":"string"},"latency_ms":{"type":"integer"},"price_x10k":{"type":"integer"},"upstream_status":{"type":"integer"},"cache_hit":{"type":"boolean"}}}}}}}},"402":{"description":"Payment required. Body is an x402 challenge — pay it and retry with x-payment header. See /.well-known/x402.json for the full profile.","content":{"application/json":{"schema":{"type":"object","required":["price","currency_base","accepts","nonce","expires_at","data_tag"],"properties":{"price":{"type":"string","description":"Decimal USD, e.g. \"0.0008\"."},"currency_base":{"const":"USD"},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["chain","token","payto","amount_raw"],"properties":{"chain":{"const":"MVX"},"token":{"type":"string","example":"EGLD"},"payto":{"type":"string","pattern":"^erd1[0-9a-z]{58}$","description":"bech32 address to pay TO."},"amount_raw":{"type":"string","pattern":"^[0-9]+$","description":"Integer string. tx.value must be ≥ this. EGLD unit is wei (10^-18 EGLD)."},"rate_x10k_per_unit":{"type":"number","description":"USD × 10^4 per 1 whole token at challenge time."}}}},"nonce":{"type":"string"},"expires_at":{"type":"integer","description":"Unix seconds."},"mcp":{"type":"string"},"tool":{"type":"string"},"data_tag":{"type":"string","pattern":"^mcpay:x402:[^:]+$","description":"Must match tx.data exactly. Encodes the nonce for replay protection."}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine code."},"hint":{"type":"string","description":"Human-readable recovery hint."}}}}}},"502":{"description":"Upstream provider failed. Call auto-refunded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine code."},"hint":{"type":"string","description":"Human-readable recovery hint."}}}}}},"503":{"description":"Gateway overloaded. Retry with backoff.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine code."},"hint":{"type":"string","description":"Human-readable recovery hint."}}}}}}}}},"/api/auth/wallet":{"post":{"summary":"Sign in with a MultiversX wallet. Upserts an agent_owners row + returns an API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["walletAddr"],"properties":{"walletAddr":{"type":"string","pattern":"^erd1[0-9a-z]{58}$"}}}}}},"responses":{"200":{"description":"Signed in","content":{"application/json":{"schema":{"type":"object","required":["ownerId","apiKey"],"properties":{"ownerId":{"type":"string"},"apiKey":{"type":"string","description":"Send as x-mcpay-key header."},"providerSlug":{"type":"string","nullable":true},"provisioning":{"type":"string","enum":["existing","created"]}}}}}},"400":{"description":"Invalid wallet","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine code."},"hint":{"type":"string","description":"Human-readable recovery hint."}}}}}}}}},"/oauth/register":{"post":{"summary":"RFC 7591 Dynamic Client Registration. Returns client_id + client_secret for self-registered agents.","responses":{"201":{},"400":{}}}},"/oauth/token":{"post":{"summary":"client_credentials grant → opaque bearer that doubles as x-mcpay-key.","responses":{"200":{},"401":{}}}}},"externalDocs":{"description":"MCPay docs + agent onboarding","url":"https://testnet.mcpay.network/llms.txt"}}