# MCPay

MCPay is a commerce layer for AI agents on MultiversX Supernova (0.6 s
blocks — https://multiversx.com/blog/andromeda-supernova-highspeed-highways).
Any agent that speaks HTTP and the open x402 payment protocol can find
our MCP services, call them, and pay per-request on-chain. No signup.
No SDK install. No human in the loop.

## Quick start — for agents, no human needed

If you are an AI agent running on a user's behalf, here is the minimum
three-step flow. Total round-trip: one HTTP 402 plus one MVX transaction.

  1. Discover:  GET  https://testnet.mcpay.network/api/catalog
                → { items: [{ slug, name, priceUsd, acceptedTokens, ... }] }

  2. Call:      POST https://testnet.mcpay.network/mcp/{slug}/{tool}
                Content-Type: application/json
                (your input JSON here)
                → HTTP 402 with an x402 challenge body. The full challenge
                  + envelope JSON Schema lives at /.well-known/x402.json —
                  parse it with any JSON Schema validator, no prose
                  required.

  3. Pay + retry: broadcast an MVX transaction where
                value   = challenge.accepts[i].amount_raw
                receiver = challenge.accepts[i].payto
                data    = challenge.data_tag  (literal UTF-8)
                sender   = your own wallet.
                Then retry the same POST with header
                x-payment: base64(JSON({ tx_hash, nonce, from }))
                → HTTP 200 with the tool result.

That's the whole contract. No account, no API key, no SDK.

Our x402 profile is tx-hash proof (the on-chain tx is the auth, not a
signed envelope). See /.well-known/x402.json for the machine-readable
profile including JSON Schemas for both the challenge and the envelope.

## Connecting as a native MCP client (Phase 4)

Every MCPay-hosted MCP is reachable as a full MCP-protocol JSON-RPC
server at `https://testnet.mcpay.network/mcp/{slug}` (no `/{tool}` suffix). This means
any MCP-spec client — Claude Desktop, Goose, VS Code Insiders,
ChatGPT Apps SDK — can connect MCPay-hosted MCPs as if they were
native MCP servers. Methods supported:

  initialize · ping · tools/list · tools/call · resources/list ·
  resources/read

Payment + identity wrap invisibly: tools/call drives the same payment
gate as the REST endpoint, returning a JSON-RPC error with code
-32002 ("payment_required") + the x402 challenge in error.data when
unpaid. Authed callers go through normally.

When MCPay forwards your tools/call upstream, your MCP server receives
these identity headers:

  x-mcpay-agent-owner   — stable opaque ID. Use as workspace key.
  x-mcpay-agent-wallet  — bech32 / 0x… (Pro Mode only).
  x-mcpay-auth-mode     — `easy` | `pro`.

Trust contract: the identity headers ARE the auth. MCPay verified the
caller before forwarding, so a stateful tool can map x-mcpay-agent-owner
→ workspace 1:1 without its own OAuth dance. See /.well-known/mcpay.json
under `mcp_protocol.identity_headers` for the full contract.

To onboard a native MCP server (no OpenAPI required), POST to
`https://testnet.mcpay.network/api/mcp/introspect` with `{ url, bearer? }` to preview
tools, then POST `https://testnet.mcpay.network/api/providers/{slug}/mcps` with
`{ ..., mcpServerUrl, mcpBearer?, mcpTools? }` to publish.

## Machine-readable surfaces (prefer these over prose)

- `https://testnet.mcpay.network/.well-known/x402.json`            — x402 profile + schemas
- `https://testnet.mcpay.network/api/openapi.json`              — OpenAPI 3.0 spec of the gateway
- `https://testnet.mcpay.network/api/catalog`                    — every MCP with pricing + tokens
- `https://testnet.mcpay.network/mcp/{slug}/.card`               — MCP card (tools + input schemas)
- `https://testnet.mcpay.network/.well-known/agent-skills/index.json` — one entry per (mcp, tool)
- `https://testnet.mcpay.network/.well-known/mcp/server-card.json`   — MCP server card (capabilities)
- `https://testnet.mcpay.network/.well-known/agent.json`             — A2A agent card
- `https://testnet.mcpay.network/.well-known/mcpay.json`             — platform manifest (all of the above, cross-linked)
- `https://testnet.mcpay.network/.well-known/oauth-authorization-server` — RFC 8414 metadata
- `https://testnet.mcpay.network/.well-known/api-catalog`            — RFC 9727 linkset
- `https://testnet.mcpay.network/.well-known/mpp.json`               — MPP profile (tx-data tagging)
- `https://testnet.mcpay.network/.well-known/acp.json`               — ACP profile (Agent Commerce Protocol, 2026-04-17)
- `https://testnet.mcpay.network/acp/checkout_sessions`            — ACP REST surface (create / get / update / complete / cancel)
- `https://testnet.mcpay.network/.well-known/ucp`                    — UCP business profile (Google Universal Commerce Protocol, v2026-04-08)

## Alternatives to x402 (if you prefer)

The x402 flow above is the default and requires zero prior knowledge
of MCPay. Two other modes exist for agents that operate on behalf of
a pre-registered owner:

  Easy Mode   — owner pre-pays a balance, agent calls with
                `x-mcpay-key: <api_key>` header. Same wallet → same
                deterministic key from /api/auth/wallet.
  OAuth 2.1   — agents self-register at /oauth/register (RFC 7591 DCR),
                exchange client_credentials at /oauth/token, then use
                `Authorization: Bearer <access_token>` on each call.
                Works interchangeably with x-mcpay-key.

Both still debit an owner's balance, so they need a funded account.
Pro Mode x402 is the only cold-start-no-signup path.

## How settlement works

Every call lands in an append-only ledger. Failed calls auto-refund
from a rolling 7-day escrow (10% of every payment is held). Providers
get 90% of gross, platform 10%, daily settled on-chain via MultiversX.
Min price per call: $0.0001. Max payload: 1 MB. Max latency: 30 s.

## AP2 mandates (optional, for Easy Mode)

Owners can issue signed spend mandates so an agent has bounded
authority instead of a blank check:
`POST /api/agents/:ownerId/mandates` → signed VC with max_spend_x10k,
allowed_mcps[], expires_at. Agent presents `x-mcpay-mandate: <id>` on
each call; gateway verifies sig + enforces ceiling + tracks consumed
spend atomically.

## Networks

One hostname per network. Gateway and site share the hostname via
path-based routing — /api/*, /mcp/*, /oauth/* hit the gateway, the
rest hits the site.

- `mcpay.network`         → mainnet (real money, planned)
- `devnet.mcpay.network`  → devnet (internal, planned)
- `testnet.mcpay.network` → testnet (Supernova sandbox, live)

Current deploy: testnet (Supernova, sandbox), chain ID `T`.

Do not mix tokens or API keys across networks — each gateway issues
its own.

## Protocols we speak (shipped)

- MCP (Anthropic) — tool interface · live
- x402 (Coinbase) — HTTP 402 wire · live, profile at /.well-known/x402.json
- OAuth 2.1 + DCR (IETF) — MCP-over-HTTP compliance · live
- AP2 (Google) — signed spend mandates · live
- MPP (Coinbase) — machine-payment tx-data tagging · live, profile at /.well-known/mpp.json
- Agent-as-Provider (MCPay) — composite MCPs with revenue split · live

## Protocols we track (not yet shipped — deliberately)

We do not implement protocols whose spec is still moving. When the
spec stabilises + a reference client exists, we add the profile.
Until then the honest answer is "not shipped":

- UCP (Google)      — universal commerce discovery. Our catalog is
                      already UCP-shaped; wrapper lands when Google
                      finalises.
- ACP (OpenAI+Stripe) — counter-offer / negotiation. Wrapper lands
                      when real agents show up wanting to haggle.
- MX-8004 (MultiversX) — on-chain agent identity NFTs. Following
                      the spec to final; no pre-implementation.

## SDK (optional)

If you happen to be writing a TypeScript agent and prefer a typed
client over raw HTTP, we ship one. The HTTP contract above is the
source of truth; the SDK is a 300-line wrapper over fetch.

```bash
npm install @mcpay/sdk
```

```ts
import { McpayClient } from '@mcpay/sdk';

const mcpay = new McpayClient({
  gatewayUrl: 'https://testnet.mcpay.network',
  apiKey: process.env.MCPAY_API_KEY!,
  network: 'testnet',
});

const account = await mcpay.call('mvx-chain-data', 'getAccount', {
  address: 'erd1…',
});
```

## Contact / docs

- Humans:  https://testnet.mcpay.network
- Docs:    https://testnet.mcpay.network/docs
- Email:   support@mcpay.network
- Chain:   https://multiversx.com