Until now, when an AI model needed access to a premium research database, real-time financial stream, or gated web scraping tool, it hit an immediate brick wall: HTTP 402 Payment Required.

With the release of the official payagents-mcp package, you can now connect PayAgents to any Model Context Protocol (MCP) client or custom agent runtime. Whether you are using desktop apps like Claude Desktop and Cursor, or building custom autonomous agents on OpenAI (GPT-4o) or Google Gemini (Gemini 2.0/1.5), your AI can autonomously evaluate 402 micro-payment challenges, pay fraction-of-a-cent fees across Bitcoin Lightning (L402) and Base USDC (x402), and fetch live data directly.

1. Connecting to Desktop Assistants (Claude Desktop, Cursor, Windsurf)

A. Claude Desktop

Open your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "payagents": {
      "command": "npx",
      "args": ["-y", "payagents-mcp"],
      "env": {
        "PAYAGENTS_API_KEY": "pa_live_your_api_key_here"
      }
    }
  }
}

B. Cursor IDE & Windsurf

In Cursor, create or edit .cursor/mcp.json in your project root or global settings:

.cursor/mcp.json

{
  "mcpServers": {
    "payagents": {
      "command": "npx",
      "args": ["-y", "payagents-mcp"],
      "env": {
        "PAYAGENTS_API_KEY": "pa_live_your_api_key_here"
      }
    }
  }
}

2. Connecting Custom Agents on OpenAI & Google Gemini

If you are building custom agents with OpenAI or Gemini SDKs, you can connect payagents-mcp directly using the MCP client SDK or standard tool calling:

A. Custom OpenAI Agent (GPT-4o / Assistants API)

openai-agent.ts

import OpenAI from 'openai';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// 1. Connect to PayAgents MCP Server
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', 'payagents-mcp'],
  env: { PAYAGENTS_API_KEY: process.env.PAYAGENTS_API_KEY! }
});
const mcpClient = new Client({ name: 'openai-agent', version: '1.0.0' }, { capabilities: {} });
await mcpClient.connect(transport);

// 2. Fetch available payment tools
const { tools } = await mcpClient.listTools();

// 3. Pass tools to OpenAI chat completions
const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Fetch report from https://premium-data.ai/q3-report' }],
  tools: tools.map(t => ({
    type: 'function',
    function: { name: t.name, description: t.description, parameters: t.inputSchema }
  }))
});

B. Custom Google Gemini Agent (Gemini 2.0 / 1.5 Pro)

gemini-agent.ts

import { GoogleGenAI } from '@google/genai';
import { PayAgents } from 'payagents';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const payagents = new PayAgents({ apiKey: process.env.PAYAGENTS_API_KEY });

// Define the PayAgents function declaration for Gemini
const payUrlTool = {
  functionDeclarations: [{
    name: 'payagents_pay_url',
    description: 'Autonomous payment for any HTTP 402 agent-gated URL (Lightning/Base USDC)',
    parameters: {
      type: 'OBJECT',
      properties: { url: { type: 'STRING', description: 'Target 402 URL to pay and unlock' } },
      required: ['url']
    }
  }]
};

// Generate content with automated function calling
const response = await ai.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Analyze market data at https://api.signals.ai/realtime',
  config: { tools: [payUrlTool] }
});

3. What Tools Does Your Agent Get?

⚡ 1. payagents_pay_url

Takes a target URL, probes the HTTP 402 payment challenge, auto-selects the fastest/cheapest rail (Lightning or Base USDC), pays the micro-fee, and returns the unlocked response data to your agent.

💳 2. payagents_get_balance

Allows your agent to check its current available USD budget and active enterprise spending policy limits before making high-frequency tool calls.

🧾 3. payagents_get_transaction

Queries transaction status, payment rails, cryptographic proof (preimage/on-chain hash), and settlement method (Direct vs Managed).

4. Enterprise Guardrails & Policy Protection

Giving an LLM an autonomous wallet might sound risky, but PayAgents was built with strict safety guardrails from day one:

Per-Transaction Limit: Your agent cannot spend more than your set ceiling on any single tool call (e.g. max $0.02).
Daily Budget Caps: Prevents runaway recursive loops from draining funds (e.g. max $5.00/day).
Domain Allowlists: You control which hostnames your agent is permitted to transact with.
Human Approval Workflow: Any payment exceeding your policy threshold is automatically paused in your dashboard until you approve it.

5. Monetizing Your Own MCP Tools with PayAgents

If you are building an MCP server and want external agents to pay you micro-fees when calling your tools:

crypto-signals.ts

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { mcpCharge } from 'payagents-mcp';
import { z } from 'zod';

const server = new McpServer({ name: 'crypto-signals', version: '1.0.0' });

// Charge $0.005 USD per tool call
server.tool(
  'get_latest_signals',
  'Retrieve real-time market signals',
  { 
    pair: z.string(),
    payment_proof: z.string().optional().describe('Payment proof for execution'),
  },
  mcpCharge({ price: '0.005 USD' }, async ({ pair }) => {
    return {
      content: [{ type: 'text', text: `Bullish momentum detected for ${pair}` }]
    };
  })
);

Earnings can settle directly into your self-custodial Base wallet or Lightning node with zero platform custody.

Ready to give your AI agent a wallet?

Get your API key in seconds and connect Claude Desktop, Cursor, OpenAI, or Gemini today.

Open Dashboard View on npm