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