Tollbooth

Solana payment URLs for AI agents — Solana Pay + x402.

Install

npm install tollbooth-pay

Quick Start

Payment URL (like Kibble, but Solana-native)

import { tollbooth, USDC } from 'tollbooth-pay';

const url = tollbooth({
  payTo: 'AgentWa11etXyz...abc',
  amount: '5',
  token: USDC.mainnet,
  agentName: 'SolBot',
});
// → https://tollbooth.pages.dev/pay?payTo=Agent...&amount=5&token=EPjF...

User opens the URL, scans the QR code or connects their wallet, and pays instantly.

Solana Pay URI (for direct QR codes)

import { solanaPay, USDC } from 'tollbooth-pay';

const { uri, reference } = solanaPay({
  payTo: 'AgentWa11etXyz...abc',
  amount: '10',
  token: USDC.mainnet,
  label: 'Agent Funding',
});
// uri → solana:AgentWa11et...?amount=10&spl-token=EPjF...&reference=...

x402 Protocol (HTTP 402 payment gating)

import { x402requirement, x402routes } from 'tollbooth-pay';

// Single requirement
const req = x402requirement({
  payTo: 'AgentWa11et...',
  amount: '0.001',
  network: 'mainnet',
});

// Route config for middleware
app.use(paymentMiddleware(
  x402routes({
    'GET /api/data': { payTo: 'Agent...', amount: '0.001', description: 'Data feed' },
    'POST /api/run': { payTo: 'Agent...', amount: '0.01', description: 'Agent execution' },
  }),
  resourceServer,
));

API

tollbooth(params) → string

Generate a hosted payment page URL.

| Param | Type | Required | Description | |-------|------|----------|-------------| | payTo | string | Yes | Solana wallet address | | amount | string | No | Amount in token units | | token | string | No | SPL token mint (default: USDC) | | network | 'mainnet' \| 'devnet' | No | Network (default: mainnet) | | agentName | string | No | Agent display name | | agentLogo | string | No | Agent logo URL | | label | string | No | Payment label | | message | string | No | Message shown to payer | | memo | string | No | On-chain memo |

solanaPay(params) → { uri, reference }

Build a Solana Pay transfer-request URI for QR codes.

x402requirement(params) → X402Requirement

Create an x402 PaymentRequirement for Solana.

x402routes(config) → RouteConfig

Build x402 middleware route configuration.

Constants

• USDC.mainnet / USDC.devnet — USDC mint addresses
• USDT.mainnet / USDT.devnet — USDT mint addresses
• NETWORKS.mainnet / NETWORKS.devnet — CAIP-2 network IDs
• SOL — null (use for native SOL transfers)

Architecture

tollbooth/
├── src/index.ts      # npm package — zero dependencies
├── web/              # Payment page — Vite + React + Solana wallet adapter
└── video/            # Remotion explainer video

License

MIT