Get Started

Choose a path

• Python (A2A): Buyer (client), standalone testing, and seller (server)
• TypeScript (MCP): Client, proxy, and FastMCP server

---

Python (A2A)

What this SDK is for

Python SDK for integrating x402 payment capabilities into A2A (Agent-to-Agent) protocol applications. Supports both buyer (client) and seller (server) roles.

Step 1: Install prerequisites and dependencies

# Install Python 3.13
uv python install 3.13

# Install dependencies
uv sync --frozen --group dev

Step 2: started (staging, testnet)

Create your first x402-enabled agent using ampersend's staging environment (free testnet).

1. Create an agent account (staging)

1. Visit https://app.staging.ampersend.ai
2. Create an agent account
3. Get your Smart Account address and session key
4. Fund with testnet USDC: https://faucet.circle.com/ (select Base Sepolia)

2. Create your buyer (client) agent

from ampersend_sdk.a2a.client import X402RemoteA2aAgent
from ampersend_sdk.ampersend import AmpersendTreasurer, ApiClient, ApiClientOptions
from ampersend_sdk.x402.wallets.smart_account import SmartAccountWallet
from ampersend_sdk.smart_account import SmartAccountConfig

# Configure smart account wallet
wallet = SmartAccountWallet(
    config=SmartAccountConfig(
        session_key="0x...",  # From staging dashboard
        smart_account_address="0x...",  # From staging dashboard
    )
)

# Create Ampersend treasurer (with spend limits & monitoring)
treasurer = AmpersendTreasurer(
    api_client=ApiClient(
        options=ApiClientOptions(
            base_url="https://api.staging.ampersend.ai",
            session_key_private_key="0x..."
        )
    ),
    wallet=wallet
)

# Create agent pointing to staging service (testnet, rate-limited)
agent = X402RemoteA2aAgent(
    treasurer=treasurer,
    name="my_agent",
    agent_card="https://subgraph-a2a.x402.staging.thegraph.com/.well-known/agent-card.json"
)

# Use the agent (payments handled automatically with spend limits)
result = await agent.run("Query Uniswap V3 pools on Base Sepolia")

Optional: Standalone mode (for testing only & not recommended)

This is a standalone example that runs without the ampersend platform. It is intended for local testing and experimentation only.

For production use, configuring agents through the ampersend platform is recommended. See the platform quick start for the supported and secure setup.

Use Standalone Mode for Testing Only:

from ampersend_sdk.a2a.client import X402RemoteA2aAgent
from ampersend_sdk.x402.treasurers.naive import NaiveTreasurer
from ampersend_sdk.x402.wallets.account import AccountWallet

wallet = AccountWallet(private_key="0x...")
treasurer = NaiveTreasurer(wallet=wallet)  # Auto-approves, no limits

agent = X402RemoteA2aAgent(
    treasurer=treasurer,
    name="test_agent",
    agent_card="https://subgraph-a2a.x402.staging.thegraph.com/.well-known/agent-card.json"
)

caution

Standalone mode has no spend limits or monitoring. Recommended for testing only.

---

Optional: Server (Seller) example

Use this when you want to require payment for your agent's tools.

from google.adk.agents import Agent
from ampersend_sdk.a2a.server import to_a2a, make_x402_before_agent_callback

# Create your ADK agent with payment requirements
agent = Agent(
    name="MyAgent",
    before_agent_callback=make_x402_before_agent_callback(
        price="$0.001",
        network="base-sepolia",
        pay_to_address="0x...",
    ),
)

@agent.tool()
async def my_tool(query: str) -> str:
    return "result"

# Convert to A2A app (x402 support configured via before_agent_callback)
a2a_app = to_a2a(agent, host="localhost", port=8001)

# Serve with uvicorn
# uvicorn module:a2a_app --host 0.0.0.0 --port 8001

---

Python core concepts (quick reference)

X402Treasurer

• ampersendTreasurer (recommended): Enforces spend limits and provides monitoring via ampersend API
• NaiveTreasurer: Auto-approves all payments (useful for testing and demos only)

Wallets

• AccountWallet: EOA (Externally Owned Accounts)
• SmartAccountWallet: ERC-4337 smart accounts with ERC-1271 signatures (includes ERC-7579 OwnableValidator from Rhinestone).

Payment Flow

1. Client sends request → Server responds with PAYMENT_REQUIRED (402)
2. Treasurer authorizes payment → Payment injected into request
3. Request retried with payment → Server verifies and processes

Python development commands

# Test
uv run -- pytest

# Lint & format
uv run -- ruff check python
uv run -- ruff format python

# Type check (strict mode)
uv run -- mypy python

---

TypeScript (MCP)

What this SDK is for

TypeScript SDK for integrating x402 payment capabilities into MCP (Model Context Protocol) applications. Supports client, proxy, and server implementations with EOA and Smart Account wallets.

Step 1: Install dependencies and build

pnpm install

# Build all
pnpm build

Step 2: Quick start options

Choose one:

• MCP Client
• MCP proxy
• FastMCP server

Option A: MCP Client

import { X402McpClient } from "@ampersend_ai/ampersend-sdk/mcp/client";
import {
  AccountWallet,
  NaiveTreasurer,
} from "@ampersend_ai/ampersend-sdk/x402";

const wallet = new AccountWallet("0x...");
const treasurer = new NaiveTreasurer(wallet);

const client = new X402McpClient({
  serverUrl: "http://localhost:8000/mcp",
  treasurer,
});

await client.connect();
const result = await client.callTool("my_tool", { arg: "value" });
await client.close();

Option B: MCP Proxy

# Configure environment
export BUYER_PRIVATE_KEY=0x...

# Start proxy
pnpm --filter ampersend-sdk proxy:dev

# Connect to: http://localhost:3000/mcp?target=http://original-server:8000/mcp

Option C: FastMCP Server

import { withX402Payment } from "@ampersend_ai/ampersend-sdk/mcp/server/fastmcp";
import { FastMCP } from "fastmcp";

const mcp = new FastMCP("my-server");

mcp.addTool({
  name: "paid_tool",
  description: "A tool that requires payment",
  schema: z.object({ query: z.string() }),
  execute: withX402Payment({
    onExecute: async ({ args }) => {
      return { scheme: "erc20", amount: "1000000" };
    },
    onPayment: async ({ payment, requirements }) => {
      return { success: true };
    },
  })(async (args, context) => {
    return "result";
  }),
});

---

Typescript core concepts (quick reference)

X402Treasurer

Handles payment authorization decisions and status tracking. The NaiveTreasurer implementation auto-approves all payments (useful for testing and demos).

Wallets

• AccountWallet - For EOA (Externally Owned Accounts)
• SmartAccountWallet - For ERC-4337 smart accounts with ERC-1271 signatures

Payment Flow

1. Client makes request → Server returns 402 with payment requirements
2. Treasurer authorizes payment → Payment injected into request metadata
3. Request retried with payment → Server verifies and processes

Environment variables (TypeScript)

# EOA Mode
BUYER_PRIVATE_KEY=0x...

# Smart Account Mode
BUYER_SMART_ACCOUNT_ADDRESS=0x...
BUYER_SMART_ACCOUNT_KEY_PRIVATE_KEY=0x...
BUYER_SMART_ACCOUNT_VALIDATOR_ADDRESS=0x...

Package exports (TypeScript)

import { ... } from "@ampersend_ai/ampersend-sdk"                  // Main
import { ... } from "@ampersend_ai/ampersend-sdk/x402"             // Core x402
import { ... } from "@ampersend_ai/ampersend-sdk/mcp/client"       // Client
import { ... } from "@ampersend_ai/ampersend-sdk/mcp/proxy"        // Proxy
import { ... } from "@ampersend_ai/ampersend-sdk/smart-account"    // Smart accounts
import { ... } from "@ampersend_ai/ampersend-sdk/mcp/server/fastmcp" // FastMCP

TypeScript development commands

# Build
pnpm --filter  build

# Test
pnpm --filter ampersend-sdk test

# Lint & format
pnpm --filter ampersend-sdk lint
pnpm --filter ampersend-sdk format:fix

Learn More

• x402 Specification
• SDK Package Documentation