JavaScript/TypeScript

Complete examples for integrating MCP-native x402 payment capabilities into AI agents using JavaScript and TypeScript.

Installation

# Install MCP client library
npm install @modelcontextprotocol/sdk

# For WebSocket support
npm install ws

# Optional: OpenAI SDK for agent integration
npm install openai

Quick Start

Connect to Claw402 MCP Server

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

// Connect to Claw402 MCP server
const transport = new StdioClientTransport({
  command: 'claw402',
  args: [
    'serve',
    '--network', 'mainnet-beta',
    '--wallet', '~/.config/solana/agent.json'
  ]
});

const client = new Client({
  name: 'payment-agent',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log('Available MCP tools:', tools.map(t => t.name));

Initialize Payment Session

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

async function initializePayment(
  client: Client,
  amount: string,
  recipient: string,
  purpose: string
) {
  const result = await client.callTool({
    name: 'x402.initialize_payment',
    arguments: {
      amount,
      recipient,
      purpose,
      settlement_constraint: 'immediate'
    }
  });

  if (result.isError) {
    throw new Error(`Payment initialization failed: ${result.content}`);
  }

  const session = JSON.parse(result.content[0].text);
  console.log('Payment session created:', session.session_id);
  return session;
}

// Usage
const session = await initializePayment(
  client,
  '0.1 SOL',
  '[email protected]',
  'API access subscription'
);

MCP Tool Integration

Complete Payment Flow

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

class X402PaymentAgent {
  constructor(private client: Client) {}

  async executePayment(
    amount: string,
    recipient: string,
    purpose: string
  ): Promise<string> {
    // Step 1: Initialize payment session
    const sessionResult = await this.client.callTool({
      name: 'x402.initialize_payment',
      arguments: { amount, recipient, purpose }
    });

    const session = JSON.parse(sessionResult.content[0].text);

    // Step 2: Authorize transaction
    const txResult = await this.client.callTool({
      name: 'x402.authorize_transaction',
      arguments: {
        session_id: session.session_id,
        approval_token: 'auto'
      }
    });

    const tx = JSON.parse(txResult.content[0].text);

    // Step 3: Verify settlement
    await this.waitForSettlement(tx.tx_signature);

    return tx.tx_signature;
  }

  async waitForSettlement(
    txSignature: string,
    timeout: number = 60000
  ): Promise<void> {
    const start = Date.now();

    while (Date.now() - start < timeout) {
      const result = await this.client.callTool({
        name: 'x402.verify_settlement',
        arguments: { tx_signature: txSignature }
      });

      const settlement = JSON.parse(result.content[0].text);

      if (settlement.confirmations >= 32) {
        console.log('Transaction finalized');
        return;
      }

      await new Promise(resolve => setTimeout(resolve, 2000));
    }

    throw new Error('Settlement timeout');
  }

  async queryBalance(wallet?: string): Promise<number> {
    const result = await this.client.callTool({
      name: 'x402.query_balance',
      arguments: wallet ? { wallet } : {}
    });

    const balance = JSON.parse(result.content[0].text);
    return balance.sol_balance;
  }

  async estimateFees(amount: string, recipient: string): Promise<number> {
    const result = await this.client.callTool({
      name: 'x402.estimate_fees',
      arguments: { amount, recipient }
    });

    const fees = JSON.parse(result.content[0].text);
    return fees.total_fees_lamports;
  }
}

// Usage
const agent = new X402PaymentAgent(client);

const txSignature = await agent.executePayment(
  '0.05 SOL',
  '[email protected]',
  'Invoice #4291 payment'
);

console.log('Payment completed:', txSignature);

AI Agent Integration with OpenAI

OpenAI Agent with MCP Tools

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

class AIPaymentAgent {
  private openai: OpenAI;
  private mcpClient: Client;

  constructor(mcpClient: Client, openaiApiKey: string) {
    this.mcpClient = mcpClient;
    this.openai = new OpenAI({ apiKey: openaiApiKey });
  }

  async processNaturalLanguagePayment(instruction: string): Promise<string> {
    // Convert MCP tools to OpenAI function schema
    const tools = await this.getMCPToolsAsOpenAIFunctions();

    const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
      {
        role: 'system',
        content: `You are a payment assistant with access to x402 protocol tools.
You can initialize payments, authorize transactions, verify settlements, and query balances.
Always confirm transaction details before authorizing.`
      },
      {
        role: 'user',
        content: instruction
      }
    ];

    while (true) {
      const response = await this.openai.chat.completions.create({
        model: 'gpt-4',
        messages,
        tools
      });

      const choice = response.choices[0];

      if (choice.finish_reason === 'tool_calls') {
        messages.push(choice.message);

        // Execute tool calls via MCP
        for (const toolCall of choice.message.tool_calls || []) {
          const result = await this.executeMCPTool(
            toolCall.function.name,
            JSON.parse(toolCall.function.arguments)
          );

          messages.push({
            role: 'tool',
            tool_call_id: toolCall.id,
            content: JSON.stringify(result)
          });
        }
      } else {
        return choice.message.content || '';
      }
    }
  }

  private async getMCPToolsAsOpenAIFunctions() {
    const { tools } = await this.mcpClient.listTools();

    return tools.map(tool => ({
      type: 'function' as const,
      function: {
        name: tool.name,
        description: tool.description,
        parameters: tool.inputSchema
      }
    }));
  }

  private async executeMCPTool(name: string, args: any) {
    const result = await this.mcpClient.callTool({
      name,
      arguments: args
    });

    if (result.isError) {
      return { error: result.content };
    }

    return JSON.parse(result.content[0].text);
  }
}

// Usage
const aiAgent = new AIPaymentAgent(mcpClient, process.env.OPENAI_API_KEY!);

const response = await aiAgent.processNaturalLanguagePayment(
  'Pay the invoice from Acme Corp for 0.05 SOL'
);

console.log(response);
// Output: "I've successfully paid the invoice from Acme Corp for 0.05 SOL.
//          Transaction signature: 3x7k..."

Autonomous Agent Use Cases

Invoice Settlement Agent

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

interface Invoice {
  id: string;
  vendor: string;
  amount: string;
  dueDate: Date;
  description: string;
}

class InvoiceAgent {
  constructor(private mcpClient: Client) {}

  async processInvoices(invoices: Invoice[]): Promise<void> {
    for (const invoice of invoices) {
      try {
        if (this.shouldProcessInvoice(invoice)) {
          await this.payInvoice(invoice);
          console.log(`✅ Paid invoice ${invoice.id}`);
        } else {
          console.log(`⚠️  Invoice ${invoice.id} requires manual review`);
        }
      } catch (error) {
        console.error(`❌ Failed to process ${invoice.id}:`, error);
      }
    }
  }

  private shouldProcessInvoice(invoice: Invoice): boolean {
    // Validation logic
    const amount = parseFloat(invoice.amount.split(' ')[0]);
    return amount <= 100 && invoice.dueDate > new Date();
  }

  private async payInvoice(invoice: Invoice): Promise<void> {
    const result = await this.mcpClient.callTool({
      name: 'x402.initialize_payment',
      arguments: {
        amount: invoice.amount,
        recipient: invoice.vendor,
        purpose: `Invoice ${invoice.id}`,
        idempotency_key: `invoice_${invoice.id}`
      }
    });

    const session = JSON.parse(result.content[0].text);

    await this.mcpClient.callTool({
      name: 'x402.authorize_transaction',
      arguments: {
        session_id: session.session_id,
        approval_token: 'auto'
      }
    });
  }
}

// Usage
const agent = new InvoiceAgent(mcpClient);
await agent.processInvoices([
  {
    id: 'INV-001',
    vendor: '[email protected]',
    amount: '50 USDC',
    dueDate: new Date('2026-04-01'),
    description: 'Cloud hosting services'
  }
]);

Subscription Renewal Agent

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

interface Subscription {
  serviceName: string;
  providerWallet: string;
  monthlyCost: string;
  expiresAt: Date;
}

class SubscriptionAgent {
  constructor(private mcpClient: Client) {}

  async checkAndRenewSubscriptions(
    subscriptions: Subscription[]
  ): Promise<void> {
    for (const sub of subscriptions) {
      if (this.shouldRenew(sub)) {
        await this.renewSubscription(sub);
      }
    }
  }

  private shouldRenew(subscription: Subscription): boolean {
    const daysUntilExpiry = Math.floor(
      (subscription.expiresAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24)
    );
    return daysUntilExpiry <= 7;
  }

  private async renewSubscription(subscription: Subscription): Promise<void> {
    try {
      // Check balance first
      const balanceResult = await this.mcpClient.callTool({
        name: 'x402.query_balance',
        arguments: {}
      });

      const balance = JSON.parse(balanceResult.content[0].text);

      // Initialize payment
      const result = await this.mcpClient.callTool({
        name: 'x402.initialize_payment',
        arguments: {
          amount: subscription.monthlyCost,
          recipient: subscription.providerWallet,
          purpose: `Renew ${subscription.serviceName}`,
          idempotency_key: `sub_${subscription.serviceName}_${Date.now()}`
        }
      });

      const session = JSON.parse(result.content[0].text);

      // Authorize
      await this.mcpClient.callTool({
        name: 'x402.authorize_transaction',
        arguments: {
          session_id: session.session_id
        }
      });

      console.log(`✅ Renewed ${subscription.serviceName}`);
    } catch (error) {
      console.error(`❌ Failed to renew ${subscription.serviceName}:`, error);
    }
  }
}

// Schedule to run daily
const subAgent = new SubscriptionAgent(mcpClient);

setInterval(
  async () => {
    await subAgent.checkAndRenewSubscriptions(subscriptions);
  },
  24 * 60 * 60 * 1000 // Daily
);

WebSocket Transaction Monitoring

Real-Time Transaction Updates

import WebSocket from 'ws';

interface TransactionUpdate {
  signature: string;
  status: 'pending' | 'confirmed' | 'finalized';
  confirmations: number;
}

class TransactionMonitor {
  private ws: WebSocket | null = null;

  constructor(
    private apiKey: string,
    private walletAddress: string
  ) {}

  connect(): void {
    this.ws = new WebSocket('wss://api.claw402.xyz/v1/transactions/stream');

    this.ws.on('open', () => {
      console.log('Connected to transaction stream');

      // Authenticate
      this.send({
        type: 'authenticate',
        api_key: this.apiKey
      });

      // Subscribe to wallet
      this.send({
        type: 'subscribe',
        wallet: this.walletAddress
      });
    });

    this.ws.on('message', (data: string) => {
      const update: TransactionUpdate = JSON.parse(data);
      this.handleUpdate(update);
    });

    this.ws.on('error', (error) => {
      console.error('WebSocket error:', error);
    });

    this.ws.on('close', () => {
      console.log('Disconnected, reconnecting in 5s...');
      setTimeout(() => this.connect(), 5000);
    });
  }

  private send(data: any): void {
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(data));
    }
  }

  private handleUpdate(update: TransactionUpdate): void {
    console.log(`Transaction ${update.signature}:`);
    console.log(`  Status: ${update.status}`);
    console.log(`  Confirmations: ${update.confirmations}`);

    if (update.status === 'finalized') {
      console.log('  ✅ Transaction finalized');
    }
  }

  disconnect(): void {
    this.ws?.close();
  }
}

// Usage
const monitor = new TransactionMonitor(
  process.env.CLAW402_API_KEY!,
  'YOUR_AGENT_WALLET'
);
monitor.connect();

Error Handling

Retry Logic with Exponential Backoff

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

class ResilientPaymentAgent {
  constructor(private mcpClient: Client) {}

  async executePaymentWithRetry(
    amount: string,
    recipient: string,
    maxRetries: number = 3
  ): Promise<string | null> {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      try {
        // Initialize payment
        const sessionResult = await this.mcpClient.callTool({
          name: 'x402.initialize_payment',
          arguments: {
            amount,
            recipient,
            idempotency_key: `payment_${recipient}_${amount}`
          }
        });

        if (sessionResult.isError) {
          throw new Error(sessionResult.content[0].text);
        }

        const session = JSON.parse(sessionResult.content[0].text);

        // Authorize transaction
        const txResult = await this.mcpClient.callTool({
          name: 'x402.authorize_transaction',
          arguments: {
            session_id: session.session_id
          }
        });

        if (txResult.isError) {
          const error = JSON.parse(txResult.content[0].text);

          if (error.code === 'INSUFFICIENT_BALANCE') {
            console.error('❌ Insufficient balance');
            return null;
          }

          if (error.code === 'RATE_LIMIT_EXCEEDED') {
            const retryAfter = error.retry_after || Math.pow(2, attempt);
            console.log(`⏳ Rate limited, retrying in ${retryAfter}s`);
            await this.sleep(retryAfter * 1000);
            continue;
          }

          throw new Error(error.message);
        }

        const tx = JSON.parse(txResult.content[0].text);
        return tx.tx_signature;

      } catch (error) {
        if (attempt < maxRetries - 1) {
          const delay = Math.pow(2, attempt) * 1000;
          console.log(`⚠️  Attempt ${attempt + 1} failed, retrying in ${delay}ms`);
          await this.sleep(delay);
          continue;
        }

        console.error(`❌ Payment failed after ${maxRetries} attempts:`, error);
        return null;
      }
    }

    return null;
  }

  private sleep(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// Usage
const agent = new ResilientPaymentAgent(mcpClient);
const txSig = await agent.executePaymentWithRetry(
  '0.05 SOL',
  '[email protected]'
);

Express.js API with MCP Backend

Payment-Protected API Endpoints

import express from 'express';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const app = express();
app.use(express.json());

let mcpClient: Client;

// Initialize MCP client
async function initMCP() {
  // ... MCP client initialization
  return client;
}

// Middleware to verify payment
async function requirePayment(
  amount: string,
  purpose: string
) {
  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
    const sessionId = req.headers['x-payment-session'] as string;

    if (!sessionId) {
      return res.status(402).json({
        error: 'Payment Required',
        message: 'Initialize payment session first'
      });
    }

    try {
      // Verify session is authorized
      const result = await mcpClient.callTool({
        name: 'x402.verify_settlement',
        arguments: { session_id: sessionId }
      });

      if (result.isError) {
        return res.status(402).json({
          error: 'Invalid payment session'
        });
      }

      next();
    } catch (error) {
      res.status(500).json({ error: 'Payment verification failed' });
    }
  };
}

// Protected endpoint
app.get(
  '/api/premium-data',
  requirePayment('0.01 SOL', 'API access'),
  (req, res) => {
    res.json({ data: 'Your premium data' });
  }
);

// Initialize payment endpoint
app.post('/api/initialize-payment', async (req, res) => {
  const { amount, purpose } = req.body;

  try {
    const result = await mcpClient.callTool({
      name: 'x402.initialize_payment',
      arguments: { amount, purpose }
    });

    const session = JSON.parse(result.content[0].text);
    res.json({ session_id: session.session_id });
  } catch (error) {
    res.status(500).json({ error: 'Payment initialization failed' });
  }
});

// Start server
mcpClient = await initMCP();
app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Best Practices

1. Idempotency Keys: Always use idempotency keys to prevent duplicate transactions

2. Error Handling: Implement retry logic with exponential backoff for transient errors

3. Monitoring: Set up WebSocket streams for real-time transaction monitoring

4. Type Safety: Use TypeScript for better type safety with MCP tool calls

5. Environment Variables: Store API keys and wallet paths in environment variables

6. Logging: Log all payment operations for audit trails

7. Testing: Test on devnet before deploying to mainnet

Next Steps

• See Python/OpenClaw examples for Python integration

• Check out MCP Tool Reference for complete tool schemas

• Read Authentication for security best practices