Skip to main content

X402 Provider

X402 is an on-chain payment protocol for MCP tools. With Mode.X402, your server returns an x402 payment request and the client replies with a payment signature that your server settles on-chain.

Use X402 only if you control the client or know it supports x402. Most major MCP clients do not support it yet.

Requirements​

  • Mode.X402 (x402 works only with the x402 provider)
  • payTo address (where to receive funds)
  • Facilitator access for real networks (CDP requires apiKeyId + apiKeySecret)

Quick Setup​

1. Configure the Provider​

The minimal configuration requires a payTo entry and CDP facilitator credentials. By default, payments are processed on Base mainnet (eip155:8453).

from paymcp import PayMCP, Mode
from paymcp.providers import X402Provider

PayMCP(
    mcp,
    providers=[
        X402Provider(
            payTo=[{"address": "0xYourAddress"}], 
            facilitator={"apiKeyId":"YOUR_CDP_KEY_ID","apiKeySecret":"YOUR_CDP_KEY_SECRET"})
    ],
    mode=Mode.X402
)

2. Choose a Network​

Supported networks:

  • Base mainnet: eip155:8453 (default)
  • Base sepolia: eip155:84532
  • Solana devnet: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
  • Solana mainnet: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

Add a network to payTo when needed:

X402Provider(
    payTo=[{"address": "0xYourAddress", "network": "eip155:84532"}]
)

3. Facilitator Credentials​

  • Mainnet usage defaults to the CDP facilitator and requires apiKeyId + apiKeySecret.
X402Provider(
    payTo=[{"address": "0xYourAddress"}],
    facilitator={"apiKeyId": "cdp_key_id", "apiKeySecret": "cdp_secret"}
)
  • Test networks (like Base sepolia) can use the free facilitator with no API keys.
X402Provider(
    payTo=[{"address": "0xYourAddress"}],
    facilitator={"url": "https://www.x402.org/facilitator"}
)

Client Integration Notes​

  • The payment signature can be provided in headers: payment-signature or x-payment.
  • MCP clients may place it in _meta["x402/payment"] (per the x402 MCP transport spec).

Mode.AUTO With Two Providers​

You can configure X402 alongside a traditional provider. In Mode.AUTO, PayMCP will prefer X402 when the client supports it, otherwise it falls back to the usual elicitation/resubmit flow with traditional provider.

PayMCP(
    mcp,
    providers={
        "x402": X402Provider(payTo=[{"address": "0xYourAddress"}]),
        "stripe": StripeProvider(apiKey="sk_test_...")
    },
    mode=Mode.AUTO
)

References​