🤖 {xpay✦} Agent Kit

Build payment-enabled agents in 5 minutes

Complete TypeScript monorepo with working agent examples that can autonomously pay for API access using payment protocols like x402, AP2, and more.

✨ Quick Start

Get a working payment-enabled agent in under 5 minutes:

# 1. Clone and install
git clone https://github.com/xpaysh/agent-kit.git
cd agent-kit
pnpm install

# 2. Set up environment
cp .env.example .env
# Edit .env with your keys (see setup section below)

# 3. Start the mock API
npm run docker:up

# 4. Run an example agent
npm run start:demo

Your agent will start making autonomous payments for premium API access! 🎉

🏗️ What's Included

This monorepo provides everything you need to build x402-paying agents:

📦 Core Packages

@xpaysh/agent-kit-core - Core payment protocol client with spending controls
@xpaysh/agent-kit-langchain - LangChain tools for autonomous payments
@xpaysh/agent-kit-testing - Mock payment-protected API server for testing
@xpaysh/agent-kit-examples - Working agent implementations

🎯 Demo Application

apps/demo - Next.js web interface for testing agents

🚀 Features

🤖 Agent Capabilities

Autonomous Payments - Agents pay for API access automatically
Spending Controls - Daily limits, per-call limits, total budgets
Multi-API Support - Weather, crypto, news, data analysis APIs
Cost Transparency - Real-time cost tracking and reporting

🛡️ Safety Features

Spending Limits - Prevent runaway costs
Payment Verification - Cryptographic proof of payments
Error Recovery - Automatic retry with backoff
Audit Trail - Complete payment history

🔧 Developer Experience

TypeScript First - Full type safety
Easy Setup - Docker compose for instant development
Live Examples - Working agents you can run immediately
Comprehensive Docs - Integration guides for popular frameworks

📋 Setup

Prerequisites

Node.js 18+ and pnpm 8+
Docker and Docker Compose
Ethereum wallet with testnet funds (Base Sepolia for x402, testnet for AP2)
OpenAI API key

Environment Configuration

Create .env file:

# Required
OPENAI_API_KEY=your_openai_api_key
PRIVATE_KEY=your_ethereum_private_key

# Optional (uses defaults)
FACILITATOR_URL=http://localhost:3000
CHAIN_ID=84532
PAY_TO_ADDRESS=0x742d35Cc6631C0532925a3b8D000cE3D

Get Testnet Funds

Get Base Sepolia ETH: Base Sepolia Faucet
Get USDC: Use Circle's testnet faucet or swap ETH for USDC

⚠️ Security: Never use mainnet keys in development. Use testnet only.

🎮 Examples

🌐 Multi-API Research Agent

Interactive agent that pays for multiple services:

npm run multi-api-agent

# Try asking:
# "What's the weather in Tokyo and current Bitcoin price?"
# "Get me tech news and analyze the sentiment"
# "Compare Ethereum and Bitcoin price trends"

APIs Used:

Weather API: $0.01 per request
Crypto Prices: $0.005 per request
News API: $0.02 per request
Data Analysis: $0.05 per request

🔬 Research Agent

Automated research workflows:

npm run research-agent

Demonstrates:

Market research combining multiple APIs
Travel planning with weather data
Investment research with news + prices

📊 Data Analysis Agent

Advanced data analysis:

npm run data-agent

Shows:

Statistical analysis of datasets
Correlation analysis between variables
Trend analysis with forecasting

🏃‍♂️ Development

Start Everything

# Start all services
npm run docker:up

# Development mode
npm run dev

This starts:

Mock x402 API server (port 3001)
Local facilitator (port 3000)
Demo web app (port 3002)

API Documentation

Visit http://localhost:3001/api for complete API documentation.

Package Development

# Build all packages
npm run build

# Run tests
npm run test

# Type check
npm run typecheck

# Lint
npm run lint

🏗️ Architecture

agent-kit/
├── packages/
│   ├── core/           # Payment client & utilities
│   ├── langchain/      # LangChain integration
│   ├── mock-api/       # Test API server
│   └── examples/       # Agent implementations
├── apps/
│   └── demo/           # Web interface
└── docker-compose.yml  # Local development

Payment Flow

sequenceDiagram
    participant Agent
    participant API
    participant Blockchain
    
    Agent->>API: Request data
    API->>Agent: 402 Payment Required
    Agent->>Blockchain: Pay USDC
    Agent->>API: Retry with payment proof
    API->>Agent: Return data

🛠️ Integration

Add to Existing LangChain Agent

import { X402Agent, WeatherTool, CryptoPriceTool } from '@xpaysh/agent-kit-langchain';

const agent = new X402Agent({
  openaiApiKey: process.env.OPENAI_API_KEY!,
  privateKey: process.env.PRIVATE_KEY!,
  spendingLimits: {
    dailyLimit: 1.0,    // $1/day
    perCallLimit: 0.1   // $0.10/call
  },
  enabledTools: ['weather', 'crypto']
});

const result = await agent.invoke(
  "What's the weather in NYC and current Bitcoin price?"
);

Custom Payment Tool

import { X402Tool } from '@xpaysh/agent-kit-langchain';

const customTool = new X402Tool({
  toolName: 'premium_data',
  toolDescription: 'Access premium dataset ($0.10/request)',
  apiUrl: 'https://api.example.com/premium',
  privateKey: process.env.PRIVATE_KEY!,
  spendingLimits: { perCallLimit: 0.10 }
});

🚀 Production with Smart Proxy (Recommended)

For production deployments, use {xpay✦} Smart Proxy to route all your agent's API calls through a managed infrastructure with enterprise-grade spending controls and observability:

import { X402Agent } from '@xpaysh/agent-kit-langchain';

const agent = new X402Agent({
  openaiApiKey: process.env.OPENAI_API_KEY!,
  // Point all API calls through Smart Proxy
  proxyConfig: {
    proxyUrl: 'https://proxy.xpay.sh/your-customer-id/your-agent-id',
    apiKey: process.env.XPAY_API_KEY!
  },
  spendingLimits: {
    dailyLimit: 50.0,    // $50/day managed by Smart Proxy
    perCallLimit: 5.0    // $5/call safety limit
  }
});

// All API calls are automatically:
// ✅ Routed through Smart Proxy
// ✅ Payment-enabled (x402/AP2)  
// ✅ Spending-controlled
// ✅ Logged and monitored
// ✅ Cached for performance

const result = await agent.invoke(
  "Get weather for London, crypto prices for BTC/ETH, and latest tech news"
);

Benefits:

Zero Payment Friction: Smart Proxy handles all payment protocols automatically
Enterprise Spending Controls: Daily limits, per-call limits, budget management
Real-time Observability: Transaction logs, spending analytics, cost optimization
Multi-Protocol Support: x402, AP2, and future protocols without code changes
Performance: Intelligent caching and request optimization

Smart Proxy Features:

🛡️ Spending Controls: Prevent runaway costs with configurable limits
💳 Payment Automation: Auto-pay for x402/AP2 APIs transparently
📊 Real-time Analytics: Track spending, usage patterns, and cost optimization
⚡ Performance: Sub-500ms latency with global edge deployment
🔒 Security: Non-custodial, enterprise-grade security

Learn more about Smart Proxy →

🌐 Ecosystem Integration

Part of the {xpay✦} opensource ecosystem:

awesome-x402 - Curated payment protocol resources
x402-local - Local development environment
x402-sdk - TypeScript-first payment protocol SDK
x402-server-kit - Server middleware

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/xpaysh/agent-kit.git
cd agent-kit
pnpm install
npm run dev

📄 License

MIT License - see LICENSE for details.

🆘 Support

Documentation: Full docs
Examples: Live examples
Issues: GitHub Issues
Discord: {xpay✦} Community

🚀 Built by {xpay✦} - Enabling autonomous agents to pay for services across all payment protocols

awesome-x402 • x402-local • agent-kit • x402-sdk