Installation

This guide covers everything you need to install and configure {xpay✦} for your project.

System Requirements

Node.js: Version 18.0 or higher
Package Manager: npm, yarn, or pnpm
Crypto Wallet: MetaMask, Coinbase Wallet, or any Web3 wallet
Network: Base mainnet or testnet

Package Installation

Full Agent Kit (Recommended)

For most developers, installing the complete agent kit is the easiest way to get started:


npm install @xpaysh/agent-kit


pnpm add @xpaysh/agent-kit


yarn add @xpaysh/agent-kit


bun add @xpaysh/agent-kit

This includes all {xpay✦} components:

@xpaysh/agent-kit - Agent spending protection
@xpaysh/agent-kit - API monetization
@xpaysh/explorer - Transaction monitoring
@xpaysh/sdk - Core x402 utilities

Individual Packages

Install only what you need:

Agent protection only:


npm install @xpaysh/agent-kit


pnpm add @xpaysh/agent-kit


yarn add @xpaysh/agent-kit


bun add @xpaysh/agent-kit

API monetization only:


npm install @xpaysh/agent-kit


pnpm add @xpaysh/agent-kit


yarn add @xpaysh/agent-kit


bun add @xpaysh/agent-kit

Transaction monitoring only:


npm install @xpaysh/explorer


pnpm add @xpaysh/explorer


yarn add @xpaysh/explorer


bun add @xpaysh/explorer

Core SDK only:


npm install @xpaysh/sdk


pnpm add @xpaysh/sdk


yarn add @xpaysh/sdk


bun add @xpaysh/sdk

Environment Setup

1. Environment Variables

Create a .env.local file in your project root:


# \{xpay✦\} Configuration
XPAY_API_KEY=xpay_test_...
XPAY_PROJECT_ID=proj_...
 
# Wallet Configuration  
AGENT_WALLET_PRIVATE_KEY=0x...
RECEIVING_WALLET_ADDRESS=0x...
 
# x402 Network
X402_NETWORK=base-sepolia  # or 'base-mainnet' for production
X402_FACILITATOR_URL=https://facilitator.base.org
 
# Optional: Custom RPC
BASE_RPC_URL=https://base-sepolia.g.alchemy.com/v2/...

2. TypeScript Configuration

Add types to your tsconfig.json:


{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true
  },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "node_modules/@xpaysh/*/types/**/*"
  ]
}

3. Next.js Configuration (if using Next.js)

Update your next.config.js:


/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ['@xpaysh/agent-kit']
  },
  webpack: (config) => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      fs: false,
      net: false,
      tls: false,
    }
    return config
  }
}
 
module.exports = nextConfig

Wallet Setup

Getting Test Funds

For development and testing:

Base Sepolia Testnet:
- Get ETH: Base Sepolia Faucet
- Get USDC: Circle Faucet

Add Base Sepolia to your wallet:


Network Name: Base Sepolia
RPC URL: https://sepolia.base.org
Chain ID: 84532
Currency Symbol: ETH

Production Wallets

For production deployments:

Agent Wallets: Use HD wallets or hardware wallets for agent private keys
Receiving Wallets: Use multisig wallets for receiving payments
Key Management: Never commit private keys to version control

Framework-Specific Setup

Express.js


import express from 'express'
import { XpayPaywall } from '@xpaysh/agent-kit'
 
const app = express()
app.use(express.json())
 
// Initialize \{xpay✦\} middleware
const paywall = new Paywall({
  pricePerRequest: 0.10,
  receivingWallet: process.env.RECEIVING_WALLET_ADDRESS
})
 
app.use('/api/premium', paywall.middleware)

Fastify


import Fastify from 'fastify'
import { SmartProxy } from '@xpaysh/agent-kit'
 
const fastify = Fastify()
 
// Register \{xpay✦\} plugin
fastify.register(async function (fastify) {
  const smartProxy = new SmartProxy({
    maxDailySpend: 100
  })
  
  fastify.decorateRequest('smartProxy', smartProxy)
})

Vercel Edge Functions


import { NextRequest } from 'next/server'
import { XpayPaywall } from '@xpaysh/agent-kit'
 
export const config = {
  runtime: 'edge'
}
 
const paywall = new Paywall({
  pricePerRequest: 0.05,
  receivingWallet: process.env.RECEIVING_WALLET_ADDRESS
})
 
export default async function handler(req: NextRequest) {
  return await paywall.handleRequest(req)
}

Verification

Test your installation:


import { XpaySDK } from '@xpaysh/agent-kit'
 
async function verifyInstallation() {
  try {
    const sdk = new XpaySDK({
      apiKey: process.env.XPAY_API_KEY,
      projectId: process.env.XPAY_PROJECT_ID
    })
    
    const status = await sdk.healthCheck()
    console.log('✅ \{xpay✦\} installation verified:', status)
    
  } catch (error) {
    console.error('❌ Installation verification failed:', error)
  }
}
 
verifyInstallation()

Expected output:


✅ \{xpay✦\} installation verified: {
  status: 'healthy',
  network: 'base-sepolia',
  facilitator: 'connected',
  version: '1.0.0'
}

Common Issues

Module Resolution Errors

If you see Cannot resolve module '@xpaysh/agent-kit':


# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
 
# Or with yarn
yarn cache clean
yarn install

Wallet Connection Issues

If wallet connections fail:

Ensure you’re on the correct network (Base Sepolia for testing)
Check that your wallet has sufficient ETH for gas fees
Verify the RPC URL is accessible

TypeScript Errors

Add type declarations if needed:


// types/xpay.d.ts
declare module '@xpaysh/agent-kit' {
  export * from '@xpaysh/agent-kit/types'
}

Next Steps

Now that {xpay✦} is installed:

Need Help?

📚 Troubleshooting Guide: Common issues and solutions
💬 Discord: Get help from our community
🐛 Bug Reports: GitHub Issues