paean-pay-mcp

Stablecoin payment MCP server — USDC on Base & Solana for AI agents.

⚠ AI-Generated Software — Use at Your Own Risk

This software was generated with AI assistance. It has not been independently audited for security vulnerabilities. Use of this software for handling real funds is entirely at your own risk. The authors and contributors accept no liability for any loss of funds, security breaches, or damages resulting from use of this software. Before using with real wallets or mainnet assets, you should conduct your own security review or engage a professional auditor.

Give your AI agent economic sovereignty: accept payments for services, pay for external APIs, and transact with other agents — all through standard MCP tool calls.

Quick Start

No install needed — run directly with npx or bunx:

npx paean-pay-mcp
# or
bunx paean-pay-mcp

The server communicates via stdio and is compatible with any MCP client: PaeanClaw, OpenPaean CLI, Claude Desktop, Cursor, and more.

Why This Exists

AI agents need to transact. Whether your agent charges users for a service, pays for external API calls, or settles with other agents, it needs a payment rail that is:

• Fast — sub-second (Solana) to 2-second (Base) finality
• Cheap — fractions of a cent per transaction
• Programmable — no bank APIs, no KYC for agent-to-agent transfers
• Stablecoin-native — USDC avoids crypto volatility

This MCP server wraps both chains behind a clean set of 7 tools that any LLM agent can call.

Supported Chains

Chain	Token	Tx Cost	Finality	Best For
Base (Coinbase L2)	USDC	< $0.01	~2s	General payments, EVM ecosystem
Solana	USDC	< $0.001	~400ms	High-frequency micro-payments

Configuration

All configuration is via environment variables, passed through your MCP client config.

Wallet Configuration

The server supports two wallet modes. Private keys take precedence — if both a private key and a mnemonic are set for the same chain, the private key is used.

Option A: Private Keys (direct)

Set a separate private key per chain. Best for agents with dedicated hot-wallets.

PAYMENT_PRIVATE_KEY_BASE=0xabc...    # Hex private key for Base (EVM)
PAYMENT_PRIVATE_KEY_SOLANA=5Kb8...   # Base58 private key for Solana

Option B: Mnemonic (HD wallet)

Set a single BIP-39 mnemonic phrase to derive wallets for both chains. Compatible with Phantom, MetaMask, and other HD wallets.

PAYMENT_MNEMONIC="abandon abandon abandon ... about"     # 12 or 24 words
PAYMENT_HD_PATH_BASE="m/44'/60'/0'/0/0"                   # optional, default shown
PAYMENT_HD_PATH_SOLANA="m/44'/501'/0'/0'"                  # optional, default shown

Default derivation paths:

• Base (EVM): m/44'/60'/0'/0/0 — standard Ethereum/MetaMask path (first account)
• Solana: m/44'/501'/0'/0' — standard Phantom/Solflare path (first account)

To use a different account index, change the last number, e.g. m/44'/60'/0'/0/1 for the second Base account.

Mixing modes

You can use a private key for one chain and a mnemonic for the other:

PAYMENT_PRIVATE_KEY_BASE=0xabc...                          # direct key for Base
PAYMENT_MNEMONIC="abandon abandon abandon ... about"       # mnemonic for Solana

Environment Variables

Variable	Required	Default	Description
PAYMENT_PRIVATE_KEY_BASE	For sending†	—	Hex private key for Base wallet
PAYMENT_PRIVATE_KEY_SOLANA	For sending†	—	Base58 private key for Solana wallet
PAYMENT_MNEMONIC	For sending†	—	BIP-39 mnemonic phrase (12 or 24 words)
PAYMENT_HD_PATH_BASE	No	m/44'/60'/0'/0/0	HD derivation path for Base wallet
PAYMENT_HD_PATH_SOLANA	No	m/44'/501'/0'/0'	HD derivation path for Solana wallet
PAYMENT_RPC_URL_BASE	No	https://mainnet.base.org	Custom Base RPC endpoint
PAYMENT_RPC_URL_SOLANA	No	https://api.mainnet-beta.solana.com	Custom Solana RPC endpoint
PAYMENT_NETWORK	No	mainnet	mainnet or testnet
PAYMENT_DEFAULT_CHAIN	No	base	Default chain: base or solana

† At least one of PAYMENT_PRIVATE_KEY_* or PAYMENT_MNEMONIC is needed to send USDC. Without any wallet, the server runs in read-only mode (balance checks, transaction lookups, payment request tracking).

Testnet mode: Set PAYMENT_NETWORK=testnet to use Base Sepolia and Solana Devnet. Get test USDC from Circle's faucet.

Tools

get_wallet_address

Returns the configured wallet address(es) for the agent.

Input:

Parameter	Type	Required	Description
chain	"base" | "solana"	No	Specific chain. Omit for all chains.

Output: Wallet address(es) for the configured chains.

---

get_usdc_balance

Check the USDC balance for any wallet address.

Input:

Parameter	Type	Required	Description
address	string	No	Address to check. Defaults to the agent's own wallet.
chain	"base" | "solana"	No	Chain to check. Defaults to PAYMENT_DEFAULT_CHAIN.

Output: Balance in human-readable format (e.g. "42.50") plus raw integer.

---

create_payment_request

Create a payment request with a unique ID. The agent presents the payment details to the payer, then uses check_payment_status to verify receipt.

Input:

Parameter	Type	Required	Description
amount	string	Yes	USDC amount, e.g. "5.00"
chain	"base" | "solana"	No	Chain to receive on
memo	string	No	Note for the payment
expires_in_minutes	number	No	Expiry (default: 30 minutes)

Output: Payment ID, recipient address, amount, memo, expiry, and human-readable instructions.

---

check_payment_status

Poll the blockchain to check if a payment request has been fulfilled.

Input:

Parameter	Type	Required	Description
payment_id	string	Yes	The payment request ID

Output: Status (pending, confirmed, or expired), and transaction details if confirmed.

---

send_usdc

Execute a USDC transfer to a target address. Requires a private key.

Input:

Parameter	Type	Required	Description
to	string	Yes	Recipient address
amount	string	Yes	USDC amount, e.g. "10.00"
chain	"base" | "solana"	No	Chain to send on

Output: Transaction hash, explorer URL, and transfer details.

---

get_transaction_status

Look up any transaction by hash.

Input:

Parameter	Type	Required	Description
tx_hash	string	Yes	Transaction hash
chain	"base" | "solana"	No	Chain the tx is on

Output: Confirmation status, block number, timestamp, from/to/amount if available.

---

list_payment_requests

List all tracked payment requests from this session.

Input:

Parameter	Type	Required	Description
status	"pending" | "confirmed" | "expired"	No	Filter by status
chain	"base" | "solana"	No	Filter by chain

Output: Array of payment requests with their current status.

Integration

PaeanClaw

Add to your paeanclaw.config.json:

{
  "mcpServers": {
    "payment": {
      "command": "npx",
      "args": ["-y", "paean-pay-mcp"],
      "env": {
        "PAYMENT_PRIVATE_KEY_BASE": "${BASE_PRIVATE_KEY}",
        "PAYMENT_PRIVATE_KEY_SOLANA": "${SOLANA_PRIVATE_KEY}",
        "PAYMENT_NETWORK": "mainnet"
      }
    }
  }
}

Or use a mnemonic to derive both wallets from one seed:

{
  "mcpServers": {
    "payment": {
      "command": "npx",
      "args": ["-y", "paean-pay-mcp"],
      "env": {
        "PAYMENT_MNEMONIC": "${WALLET_MNEMONIC}",
        "PAYMENT_NETWORK": "mainnet"
      }
    }
  }
}

Then customize your AGENT.md to instruct the agent on when to charge:

## Payment Policy

You are a paid assistant. Before answering premium questions, create a payment
request for $0.10 USDC on Base. Wait for the user to pay, verify the payment
using check_payment_status, then proceed with the answer.

OpenPaean CLI

Add to ~/.openpaean/mcp_config.json (global) or .openpaean/mcp.json (project):

{
  "mcpServers": {
    "payment": {
      "command": "npx",
      "args": ["-y", "paean-pay-mcp"],
      "env": {
        "PAYMENT_PRIVATE_KEY_BASE": "0x...",
        "PAYMENT_NETWORK": "mainnet"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "payment": {
      "command": "npx",
      "args": ["-y", "paean-pay-mcp"],
      "env": {
        "PAYMENT_PRIVATE_KEY_BASE": "0x...",
        "PAYMENT_NETWORK": "testnet"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "payment": {
      "command": "npx",
      "args": ["-y", "paean-pay-mcp"],
      "env": {
        "PAYMENT_PRIVATE_KEY_BASE": "0x..."
      }
    }
  }
}

Any MCP Client

The server uses stdio transport. Configure it the same way you would any other MCP server:

command: npx
args: ["-y", "paean-pay-mcp"]
env: { PAYMENT_PRIVATE_KEY_BASE: "0x...", PAYMENT_NETWORK: "mainnet" }

Example Workflows

Agent Charges for a Service

User: "Translate this document to Japanese"
Agent: → create_payment_request(amount: "2.00", chain: "base", memo: "translation-service")
Agent: "Please send 2.00 USDC to 0xABC...123 on Base. Payment ID: a1b2c3d4"
User: *sends payment*
Agent: → check_payment_status(payment_id: "a1b2c3d4")
Agent: "Payment confirmed! Here's your translation: ..."

Agent Pays for an External API

User: "Get me the latest market analysis"
Agent: → send_usdc(to: "0xDEF...789", amount: "0.50", chain: "base")
Agent: "Paid 0.50 USDC for premium market data. Here's the analysis: ..."

Agent-to-Agent Payment

Agent A: → send_usdc(to: "SOLANA_ADDRESS", amount: "1.00", chain: "solana")
Agent B: → check_payment_status(payment_id: "...")
Agent B: "Payment received. Processing your request..."

Security

• Private keys and mnemonics are passed via environment variables and never logged or exposed through tool outputs
• When using a mnemonic, derived private keys exist only in memory and are never persisted
• Never commit private keys or mnemonics to version control. Use environment variables or a secrets manager.
• Read-only by default — without any wallet configured, no funds can be sent
• In-memory store — payment request tracking is ephemeral; restarting clears all state
• Use testnet (PAYMENT_NETWORK=testnet) for development and testing

USDC Contract Addresses

Network	Chain	Address
Mainnet	Base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Mainnet	Solana	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Testnet	Base Sepolia	0x036CbD53842c5426634e7929541eC2318f3dCF7e
Testnet	Solana Devnet	4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

Development

git clone https://github.com/paean-ai/paean-pay-mcp.git
cd paean-pay-mcp
npm install
npm run build
PAYMENT_NETWORK=testnet node dist/index.js

Test with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Requirements

• Node.js 20+ or Bun 1.0+

License

MIT