Building x402-Gated MCP Endpoints with Base L2 USDC Payments

How to build an x402-gated MCP endpoint (with real Base L2 USDC flow)

The x402 protocol enables autonomous agents to pay for API access using EIP-3009 transfer authorizations. This system allows a Global Chat directory endpoint to charge 0.10 USDC per call on the Base L2 network without human intervention.

Why This Matters

Traditional APIs rely on human-centric payment systems like credit cards and OAuth, which create friction for autonomous AI agents. By implementing x402 on Base L2 (Chain ID 8453), developers can replace manual billing with a programmatic ‘Payment Required’ challenge-response loop. This architecture shifts the burden of trust to on-chain verification, enabling a permissionless substrate where discovery, capability, and settlement occur entirely through protocol-level interactions.

Key Insights

• The x402 protocol replaces 401 Unauthorized with 402 Payment Required, returning a JSON challenge containing atomic price and recipient data.
• EIP-3009 transferWithAuthorization allows agents to sign a payload that the server submits, settling funds in a single transaction without a separate gas fee for the agent.
• Agent discovery is facilitated via the /.well-known/agent-card.json standard, which defines payment protocols and asset decimals for autonomous negotiation.
• Base L2 USDC requires specific EIP-712 domain values, specifically name ‘USD Coin’ and version ‘2’, at contract address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

Working Examples

Agent discovery entry point via agent-card.json

{
"name": "Global Chat Directory",
"payment": {
"protocol": "x402",
"chain": "base",
"chainId": 8453,
"asset": "USDC",
"assetDecimals": 6,
"recipient": "0xce90931a854a26262bA31631918ca76b21D92ad2"
}
}

Signing an EIP-3009 payment payload using viem

const signature = await client.signTypedData({
 domain: {
 name: "USD Coin",
 version: "2",
 chainId: 8453,
 verifyingContract: challenge.asset,
 },
 types: {
 TransferWithAuthorization: [
 { name: "from", type: "address" },
 { name: "to", type: "address" },
 { name: "value", type: "uint256" },
 { name: "validAfter", type: "uint256" },
 { name: "validBefore", type: "uint256" },
 { name: "nonce", type: "bytes32" },
 ],
 },
 primaryType: "TransferWithAuthorization",
 message: {
 from: account.address,
 to: challenge.recipient,
 value: BigInt(challenge.price),
 validAfter: 0n,
 validBefore: BigInt(challenge.validUntil),
 nonce: nonceHex,
 },
});

Practical Applications

• Use case: Global Chat Directory uses x402 to gate access to its agent feed. Pitfall: Setting a short validUntil window (e.g., 30 seconds) can cause on-chain reverts if server processing takes too long.
• Use case: MCP tool calls requiring paid data for caching. Pitfall: Reusing nonces for the same from/to pair, which makes the second transaction call fail on-chain.

References:

• https://dev.to/globalchatapp/how-to-build-an-x402-gated-mcp-endpoint-with-real-base-l2-usdc-flow-3mh8