x402-dev

name: x402-dev description: | Comprehensive development support for x402 protocol — the open HTTP payment standard built on HTTP 402. Covers client (buyer) integration, server (seller) middleware, MCP server monetization, and AWS CloudFront/Lambda@Edge deployments.

USE THIS SKILL whenever the user:

• Asks about x402, HTTP 402 payments, or machine-to-machine micropayments
• Wants to add pay-per-request pricing to an API, endpoint, or HTTP resource
• Integrates x402 with Express, Next.js, Hono, FastAPI, Flask, or any HTTP framework
• Builds an AI agent that pays for tools/APIs automatically (agentic commerce)
• Implements an MCP server with payment-gated tools
• Deploys x402 on AWS CloudFront, Lambda@Edge, or AgentCore
• Needs wallet setup, facilitator config, EVM/Solana network configuration, or USDC payments
• Asks about Bazaar service discovery, x402 whitepaper concepts, or x402 architecture
• Migrates from testnet (Base Sepolia) to mainnet (Base Mainnet / Solana Mainnet)

Even if the user just says "add payments to my API", "charge per API call", or "monetize my HTTP endpoint", invoke this skill.

x402 Development Guide

x402 is an open payment standard that extends HTTP 402 to enable programmatic, account-free micropayments between clients and servers — natively supporting AI agent autonomous payments.

Quick Orientation

Payment Flow:

1. Client requests resource → Server returns 402 with X-PAYMENT-REQUIRED header
2. Client creates signed payment payload → retries with X-PAYMENT-SIGNATURE header
3. Server verifies via facilitator → settles on-chain → returns 200

Package Reference

TypeScript / Node.js

# Client (buyer)
npm install @x402/core @x402/evm @x402/fetch    # fetch-based
npm install @x402/core @x402/evm @x402/axios    # axios-based
npm install @x402/core @x402/svm @x402/fetch    # Solana client

# Server (seller)
npm install @x402/express    # Express.js
npm install @x402/next       # Next.js
npm install @x402/hono       # Hono

# MCP integration
npm install @x402/mcp

Python

pip install x402                # base
pip install x402[httpx]         # async httpx client
pip install x402[requests]      # sync requests client
pip install x402[fastapi]       # FastAPI middleware
pip install x402[flask]         # Flask middleware
pip install x402[svm]           # Solana support

Network & Facilitator Configuration

Always start on testnet. For mainnet migration see [references/networks.md].

Implementation Paths

Choose your path and read the reference file:

Minimal Working Examples

Client (Buyer) — TypeScript

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Automatically handles 402 → sign → retry
const response = await fetchWithPayment("https://api.example.com/paid-endpoint");
const data = await response.json();

Server (Seller) — Express.js

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const app = express();

const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });
const server = new x402ResourceServer(facilitator)
  .register("eip155:84532", new ExactEvmScheme());

app.use(paymentMiddleware({
  "GET /weather": {
    accepts: [{
      scheme: "exact",
      price: "$0.001",
      network: "eip155:84532",
      payTo: process.env.WALLET_ADDRESS!,
    }],
    description: "Real-time weather data",
    mimeType: "application/json",
  },
}, server));

app.get("/weather", (req, res) => {
  res.json({ weather: "sunny", temperature: 72 });
});

app.listen(4021);

MCP Server — Payment-Gated Tool

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { x402MCPServer } from "@x402/mcp";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const mcpServer = new McpServer({ name: "paid-tools", version: "1.0.0" });

const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });
const x402Server = new x402MCPServer(facilitator)
  .register("eip155:84532", new ExactEvmScheme());

// Wrap a tool with payment requirement
x402Server.wrapTool(mcpServer, "get_premium_data", {
  accepts: [{
    scheme: "exact",
    price: "$0.001",
    network: "eip155:84532",
    payTo: process.env.WALLET_ADDRESS!,
  }],
  handler: async (params) => ({ data: "premium content" }),
});

Route Configuration Schema

interface RouteConfig {
  accepts: Array<{
    scheme: string;    // "exact" (fixed) or "upto" (consumption-based)
    price: string;     // Dollar format: "$0.001"
    network: string;   // CAIP-2 identifier
    payTo: string;     // Wallet address to receive payment
    asset?: string;    // Token contract address (auto-resolved if omitted)
  }>;
  description?: string;
  mimeType?: string;
  extensions?: {
    bazaar?: {
      discoverable: boolean;
      category: string;
      tags: string[];
    };
  };
}

Common Issues & Solutions

Environment Variables

# Client (buyer)
EVM_PRIVATE_KEY=0x...          # EVM wallet private key
SVM_PRIVATE_KEY=...            # Solana wallet private key (base58)

# Server (seller)
WALLET_ADDRESS=0x...           # Address to receive payments
FACILITATOR_URL=https://x402.org/facilitator  # testnet

# AWS / AgentCore
CDP_API_KEY_ID=...
CDP_API_KEY_SECRET=...
CDP_WALLET_SECRET=...
SELLER_API_URL=https://dXXX.cloudfront.net

Bazaar Service Discovery

Register your API for discoverability:

"GET /weather": {
  accepts: [{ scheme: "exact", price: "$0.001", network: "eip155:8453", payTo: "0x..." }],
  extensions: {
    bazaar: {
      discoverable: true,
      category: "weather",
      tags: ["forecast", "real-time"],
    },
  },
}

Query the Bazaar:

const response = await fetch("https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources");
const { items } = await response.json();
const affordable = items.filter(item =>
  item.accepts.some(req => Number(req.amount) < 100000)
);

Reference Files

• [references/client.md] — Full client patterns: fetch, axios, multi-network, error handling, AI agent integration
• [references/server.md] — Full server patterns: Express, Next.js, Hono, Python FastAPI/Flask, route config
• [references/mcp-server.md] — MCP server monetization: tool wrapping, payment lifecycle hooks, Claude integration
• [references/aws-cloudfront.md] — CloudFront + Lambda@Edge: CDK stack, payment verifier, AgentCore, 3-step flow
• [references/networks.md] — Network IDs, facilitators, testnet/mainnet migration, USDC addresses