USDC payments for bots via the x402 protocol. One dependency (viem), 7 files, typed everything.
- One dependency (
viem), 7 files, fully typed - Simple API — register your bot and make payments in 2 lines of code
- Network support — Base and Base Sepolia (EIP155)
- Mock mode for testing without real transactions
- MCP integration — works with AI agent frameworks via
paybot-mcp - Self-hostable facilitator service
PayBotClient → Facilitator (x402) → On-chain USDC (EIP-3009)
The SDK wraps payment logic for bots, handling registration, payment execution, and network configuration. Developers can use the hosted facilitator at api.paybotcore.com or run their own.
npm install paybot-sdkimport { PayBotClient } from 'paybot-sdk';
const client = new PayBotClient({
apiKey: 'pb_test_...',
botId: 'my-bot',
facilitatorUrl: 'https://api.paybotcore.com',
});
// Register your bot
await client.register();
// Make a payment
const result = await client.pay({
resource: 'https://api.example.com/data',
amount: '0.01',
payTo: '0x1234...abcd',
});
console.log(result.success, result.txHash);Automatically pay for HTTP 402 responses:
import { createX402Handler } from 'paybot-sdk';
const handler = createX402Handler({
apiKey: 'pb_test_...',
botId: 'my-bot',
maxAutoPay: '1.00', // Max USD per auto-payment
});
// If the server returns 402, PayBot pays and retries automatically
const response = await handler.fetch('https://api.example.com/paid-endpoint');
const data = await response.json();Pass a wallet private key to sign actual on-chain USDC transfers:
const client = new PayBotClient({
apiKey: 'pb_...',
botId: 'my-bot',
walletPrivateKey: '0x...', // Signs EIP-3009 TransferWithAuthorization
});PayBot enforces progressive trust levels that govern what your bot can do:
| Level | Name | Per-Tx Limit | Daily Limit |
|---|---|---|---|
| 0 | Suspended | $0 | $0 |
| 1 | New | $1 | $10 |
| 2 | Basic | $10 | $100 |
| 3 | Verified | $100 | $1,000 |
| 4 | Trusted | $1,000 | $10,000 |
| 5 | Premium | $10,000 | $100,000 |
| Method | Description |
|---|---|
client.pay(request) |
Execute a payment (verify + settle) |
client.register(trustLevel?) |
Register bot with facilitator |
client.balance() |
Get trust status and remaining budget |
client.history(limit?) |
Get transaction history |
client.setLimits(limits) |
Update spending limits |
client.health() |
Check facilitator health |
Non-pay() methods throw PayBotApiError on failure:
import { PayBotApiError } from 'paybot-sdk';
try {
await client.balance();
} catch (err) {
if (err instanceof PayBotApiError) {
console.log(err.code); // 'NOT_FOUND'
console.log(err.statusCode); // 404
console.log(err.details); // { botId: 'unknown-bot' }
}
}pay() returns PaymentResult with success: false instead of throwing:
const result = await client.pay({ ... });
if (!result.success) {
console.log(result.error); // Human-readable message
console.log(result.errorCode); // 'TRUST_VIOLATION'
console.log(result.errorDetails); // { gate: 'SPENDING_ENVELOPE', ... }
}import { NETWORKS, getNetwork, getSupportedNetworks } from 'paybot-sdk';
// Available networks
console.log(getSupportedNetworks()); // ['eip155:8453', 'eip155:84532']
// Get network details
const baseSepolia = getNetwork('eip155:84532');
console.log(baseSepolia?.name); // 'Base Sepolia'For AI agent frameworks, use paybot-mcp which wraps this SDK as an MCP server.
Use the hosted facilitator at api.paybotcore.com — no setup needed, ready to go:
const client = new PayBotClient({
apiKey: 'pb_test_...',
botId: 'my-bot',
facilitatorUrl: 'https://api.paybotcore.com', // ← Hosted
});For enterprise bots or custom networks, deploy your own PayBot facilitator with Docker (5 minutes):
git clone https://github.com/RBKunnela/paybot-core.git
cd paybot-core
docker compose up -dThen configure your bot:
const client = new PayBotClient({
apiKey: 'pb_dev_...',
botId: 'my-bot',
facilitatorUrl: 'http://localhost:3000', // ← Self-hosted
});Quick start guide: See SELF_HOSTING.md in this repository.
Full deployment guide: See DEPLOYMENT.md in paybot-core repository.