@agenttoll/sdk 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# AgentToll SDK
+
+One-line micropayment integration for AI agents.
+
+## Installation
+
+### From npm (recommended)
+```bash
+npm install @agenttoll/sdk
+```
+
+### From GitHub (if npm is unavailable)
+```bash
+npm install github:agenttoll/sdk
+```
+
+### Direct download
+Copy [tollbooth.js](./tollbooth.js) into your project.
+
+## Usage
+
+### Express
+```javascript
+import tollbooth from '@agenttoll/sdk';
+// or if installed locally:
+// import tollbooth from './tollbooth.js';
+
+app.use(tollbooth('pk_live_xxx'));
+```
+
+### Cloudflare Workers
+```javascript
+import { tollgate } from '@agenttoll/sdk/edge';
+
+export default tollgate('pk_live_xxx', { amount: 0.005 });
+```
+
+### Agent Tool (for AI agents)
+```javascript
+import { payTollTool } from '@agenttoll/sdk/tool';
+
+// Add to your agent's tools
+tools: [payTollTool]
+```
+
+## API Reference
+
+See [https://agenttoll.io/docs](https://agenttoll.io/docs) for full documentation.

package/agenttoll-tool-schema.json

@@ -0,0 +1,28 @@
+{
+  "name": "pay_toll",
+  "description": "Pay a micropayment toll to access a paywalled resource. Use this when you encounter an HTTP 402 Payment Required response. The tool handles the payment via Solana USDC and returns an access token for the resource.",
+  "strict": true,
+  "parameters": {
+    "type": "object",
+    "required": ["url", "amount"],
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "The URL of the resource that requires payment (from the 402 response)"
+      },
+      "amount": {
+        "type": "number", 
+        "description": "The payment amount in USDC (from the 402 response x402 headers or body)"
+      },
+      "max_amount": {
+        "type": "number",
+        "description": "Maximum amount you're willing to pay. If the requested amount exceeds this, the tool will not proceed. Default: 0.05 USDC"
+      },
+      "reason": {
+        "type": "string",
+        "description": "Why accessing this resource is valuable for your current task (helps with logging and human oversight)"
+      }
+    },
+    "additionalProperties": false
+  }
+}

package/agenttoll-tool.js

@@ -0,0 +1,181 @@
+/**
+ * AgentToll Tool: pay_toll
+ * 
+ * This tool allows AgentToll/OpenClaw agents to autonomously pay
+ * micropayment tolls when they hit 402 Payment Required responses.
+ * 
+ * Installation:
+ *   Add this tool to your AgentToll's tool configuration
+ * 
+ * Usage in agent prompts:
+ *   "If you encounter a 402 Payment Required error on a useful resource,
+ *    use the pay_toll tool to pay up to 0.01 USDC if the content is
+ *    valuable for the current task."
+ */
+
+import { Keypair, Connection, PublicKey, Transaction } from '@solana/web3.js';
+import { 
+  getAssociatedTokenAddress, 
+  createTransferInstruction,
+  TOKEN_PROGRAM_ID 
+} from '@solana/spl-token';
+
+const TOLL_API = 'https://toll.agenttoll.io';
+const USDC_MINT = new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'); // Mainnet USDC
+
+/**
+ * AgentToll-compatible tool implementation
+ */
+export async function pay_toll(params, context) {
+  const { url, amount, max_amount = 0.05, reason } = params;
+  const { wallet_keypair, solana_rpc } = context;
+
+  // Safety check: don't overpay
+  if (amount > max_amount) {
+    return {
+      success: false,
+      error: `Requested amount ${amount} USDC exceeds max_amount ${max_amount} USDC`,
+      suggestion: 'Increase max_amount if this resource is valuable, or skip this resource',
+    };
+  }
+
+  try {
+    // 1. Get payment details from toll service
+    const quoteRes = await fetch(`${TOLL_API}/api/pay/quote?resource=${encodeURIComponent(url)}&amount=${amount}`);
+    const quote = await quoteRes.json();
+
+    // 2. Create and send Solana USDC transfer
+    const connection = new Connection(solana_rpc || 'https://api.mainnet-beta.solana.com');
+    const payer = Keypair.fromSecretKey(wallet_keypair);
+    
+    const payerAta = await getAssociatedTokenAddress(USDC_MINT, payer.publicKey);
+    const receiverAta = await getAssociatedTokenAddress(USDC_MINT, new PublicKey(quote.receiver_wallet));
+
+    // Amount in USDC (6 decimals)
+    const transferAmount = Math.floor(amount * 1_000_000);
+
+    const transaction = new Transaction().add(
+      createTransferInstruction(
+        payerAta,
+        receiverAta,
+        payer.publicKey,
+        transferAmount,
+        [],
+        TOKEN_PROGRAM_ID
+      )
+    );
+
+    const signature = await connection.sendTransaction(transaction, [payer]);
+    await connection.confirmTransaction(signature, 'confirmed');
+
+    // 3. Submit payment proof to toll service
+    const payRes = await fetch(`${TOLL_API}/api/pay`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        publisher: quote.publisher || 'default',
+        amount: amount,
+        resource: url,
+        tx_signature: signature,
+        agent_id: context.agent_id || 'agenttoll',
+      }),
+    });
+
+    const payResult = await payRes.json();
+
+    if (!payResult.success) {
+      return {
+        success: false,
+        error: payResult.error,
+        tx_signature: signature,
+      };
+    }
+
+    // 4. Return token for agent to use
+    return {
+      success: true,
+      token: payResult.token,
+      expires_in: payResult.expires_in,
+      amount_paid: amount,
+      tx_signature: signature,
+      retry_headers: {
+        'Authorization': `Bearer ${payResult.token}`,
+      },
+      instructions: `Payment successful. Retry the original request to ${url} with the Authorization header set to: Bearer ${payResult.token}`,
+    };
+
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+      suggestion: 'Check wallet balance or try again later',
+    };
+  }
+}
+
+/**
+ * Parse 402 response to extract payment details
+ * Helper for agents to understand 402 responses
+ */
+export function parse402Response(response) {
+  // Try x402 headers first
+  const headers = response.headers || {};
+  if (headers['x-402-amount']) {
+    return {
+      amount: parseFloat(headers['x-402-amount']),
+      currency: headers['x-402-currency'] || 'USDC',
+      pay_url: headers['x-402-pay-url'],
+      network: headers['x-402-network'] || 'solana',
+    };
+  }
+
+  // Try body
+  const body = typeof response.body === 'string' ? JSON.parse(response.body) : response.body;
+  if (body?.x402) {
+    return {
+      amount: body.x402.amount,
+      currency: body.x402.currency,
+      network: body.x402.network,
+      pay_url: body.payment?.pay_url,
+    };
+  }
+
+  if (body?.payment) {
+    return {
+      amount: body.payment.amount,
+      currency: body.payment.currency,
+      network: body.payment.network,
+      pay_url: body.payment.pay_url,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * AgentToll system prompt addition for toll handling
+ */
+export const TOLL_SYSTEM_PROMPT = `
+## Toll Payment Capability
+
+You have access to the pay_toll tool for handling paywalled content. When you encounter an HTTP 402 Payment Required response:
+
+1. Check the x402 headers or response body for payment details (amount, currency, network)
+2. Evaluate if the resource is worth paying for based on your current task
+3. If valuable and within your budget (default max 0.01 USDC), use pay_toll to pay
+4. Retry the original request with the returned Authorization token
+
+Example 402 handling:
+- Receive 402 with amount: 0.005 USDC
+- Decide: "This API has data I need for my research task"
+- Call: pay_toll(url="...", amount=0.005, reason="Need this data for research")
+- Retry request with: Authorization: Bearer <returned_token>
+
+Budget guidelines:
+- Small data requests: up to 0.005 USDC
+- API calls: up to 0.01 USDC  
+- Premium content: up to 0.05 USDC (ask human first if possible)
+- Never exceed 0.1 USDC without explicit human approval
+`;
+
+export default { pay_toll, parse402Response, TOLL_SYSTEM_PROMPT };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agenttoll/sdk",
+  "version": "1.0.0",
+  "description": "One-line micropayment integration for AI agents - Express, Cloudflare Workers, Vercel Edge",
+  "main": "tollbooth.js",
+  "exports": {
+    ".": "./tollbooth.js",
+    "./edge": "./tollbooth-edge.js",
+    "./next": "./tollbooth-edge.js",
+    "./tool": "./agenttoll-tool.js"
+  },
+  "type": "module",
+  "keywords": [
+    "agenttoll",
+    "openclaw",
+    "ai-agents",
+    "micropayments",
+    "x402",
+    "solana",
+    "base",
+    "tollbooth",
+    "express-middleware",
+    "cloudflare-workers"
+  ],
+  "author": "AgentToll",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agenttoll/sdk"
+  },
+  "homepage": "https://agenttoll.io",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "tollbooth.js",
+    "tollbooth-edge.js",
+    "agenttoll-tool.js",
+    "agenttoll-tool-schema.json"
+  ]
+}

package/tollbooth-edge.js

@@ -0,0 +1,134 @@
+/**
+ * AgentToll - Edge Runtime SDK
+ * For Cloudflare Workers, Vercel Edge, Deno Deploy
+ * 
+ * @example
+ * import { tollgate } from '@agenttoll/sdk/edge'
+ * export default tollgate('your-api-key')
+ */
+
+const TOLL_API_BASE = 'https://toll.agenttoll.io';
+
+const AGENT_PATTERNS = [
+  /agenttoll/i, /openclaw/i, /clawd/i, /openai-agent/i,
+  /anthropic-agent/i, /autogpt/i, /agentgpt/i, /babyagi/i,
+];
+
+function isAgent(request) {
+  const ua = request.headers.get('user-agent') || '';
+  const agentHeader = request.headers.get('x-agent-type') || request.headers.get('x-agenttoll-id') || '';
+  if (AGENT_PATTERNS.some(p => p.test(ua))) return true;
+  if (agentHeader) return true;
+  if (request.headers.get('x-402-capable') === 'true') return true;
+  return false;
+}
+
+async function verifyToken(token, apiKey) {
+  try {
+    const res = await fetch(`${TOLL_API_BASE}/api/verify`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Publisher-Key': apiKey },
+      body: JSON.stringify({ token }),
+    });
+    return (await res.json()).valid === true;
+  } catch {
+    return false;
+  }
+}
+
+function build402(request, apiKey, amount) {
+  const url = new URL(request.url);
+  return {
+    status: 402,
+    message: 'Payment Required',
+    agent_instructions: `Pay ${amount} USDC to access. Use returned token in Authorization header.`,
+    payment: {
+      amount,
+      currency: 'USDC',
+      network: 'solana',
+      pay_url: `${TOLL_API_BASE}/pay?publisher=${apiKey}&amount=${amount}&resource=${encodeURIComponent(url.href)}`,
+      api_endpoint: `${TOLL_API_BASE}/api/pay`,
+    },
+    x402: { version: 1, amount, currency: 'USDC', network: 'solana-mainnet' },
+    retry: { method: request.method, url: url.href, headers: { 'Authorization': 'Bearer <token>' } },
+  };
+}
+
+/**
+ * Edge-compatible tollgate wrapper
+ * Wraps your handler and gates it behind payment
+ * 
+ * @example
+ * // Cloudflare Worker
+ * import { tollgate } from '@agenttoll/sdk/edge'
+ * 
+ * export default tollgate('pk_live_xxx', {
+ *   amount: 0.005,
+ *   freeForHumans: true,
+ *   handler: async (request) => {
+ *     return new Response('Premium content!')
+ *   }
+ * })
+ */
+export function tollgate(apiKey, options = {}) {
+  const amount = options.amount || 0.005;
+  const freeForHumans = options.freeForHumans ?? false;
+  const handler = options.handler;
+
+  return {
+    async fetch(request, env, ctx) {
+      const agent = isAgent(request);
+
+      // Free for humans if configured
+      if (freeForHumans && !agent) {
+        return handler ? handler(request, env, ctx) : new Response('OK');
+      }
+
+      // Check payment token
+      const auth = request.headers.get('authorization') || '';
+      const token = auth.replace(/^Bearer\s+/i, '');
+
+      if (token && await verifyToken(token, apiKey)) {
+        return handler ? handler(request, env, ctx) : new Response('OK');
+      }
+
+      // Return 402
+      const paymentInfo = build402(request, apiKey, amount);
+      return new Response(JSON.stringify(paymentInfo), {
+        status: 402,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-402-Version': '1',
+          'X-402-Amount': amount.toString(),
+          'X-402-Currency': 'USDC',
+          'X-402-Pay-URL': paymentInfo.payment.pay_url,
+        },
+      });
+    }
+  };
+}
+
+/**
+ * Middleware for edge frameworks (Hono, itty-router, etc.)
+ */
+export function tollMiddleware(apiKey, options = {}) {
+  const amount = options.amount || 0.005;
+  const freeForHumans = options.freeForHumans ?? false;
+
+  return async (request, next) => {
+    const agent = isAgent(request);
+    if (freeForHumans && !agent) return next();
+
+    const auth = request.headers.get('authorization') || '';
+    const token = auth.replace(/^Bearer\s+/i, '');
+    if (token && await verifyToken(token, apiKey)) return next();
+
+    const paymentInfo = build402(request, apiKey, amount);
+    return new Response(JSON.stringify(paymentInfo), {
+      status: 402,
+      headers: { 'Content-Type': 'application/json', 'X-402-Version': '1' },
+    });
+  };
+}
+
+export { isAgent };

package/tollbooth.js

@@ -0,0 +1,292 @@
+/**
+ * AgentToll SDK
+ * One-line integration for AI agent micropayments
+ * 
+ * Usage (Express):
+ *   app.use(require('@agenttoll/sdk')('your-api-key'))
+ * 
+ * Usage (Cloudflare Worker):
+ *   import { tollgate } from '@agenttoll/sdk/edge'
+ *   export default tollgate('your-api-key', { amount: 0.005 })
+ */
+
+const TOLL_API_BASE = process.env.TOLL_API_URL || 'https://toll.agenttoll.io';
+
+// Agent detection patterns
+const AGENT_PATTERNS = [
+  // Platform-specific
+  /agenttoll/i,
+  /openclaw/i,
+  /clawd/i,
+  // Major AI providers
+  /claude/i,
+  /anthropic/i,
+  /openai/i,
+  /gpt-4/i,
+  /chatgpt/i,
+  /gemini/i,
+  /google-ai/i,
+  // Agent frameworks
+  /langchain/i,
+  /autogpt/i,
+  /agentgpt/i,
+  /babyagi/i,
+  /crewai/i,
+  /superagent/i,
+  // Generic patterns
+  /ai-agent/i,
+  /bot\//i,
+  /agent\//i,
+];
+
+/**
+ * Detect if request is from an AgentToll/AI agent
+ */
+function isAgent(req) {
+  const ua = req.headers['user-agent'] || '';
+  const agentHeader = req.headers['x-agent-type'] || req.headers['x-agenttoll-id'] || '';
+  
+  // Check User-Agent
+  if (AGENT_PATTERNS.some(pattern => pattern.test(ua))) return true;
+  
+  // Check custom agent headers
+  if (agentHeader) return true;
+  
+  // Check x402 capability header (agents advertise payment capability)
+  if (req.headers['x-402-capable'] === 'true') return true;
+  
+  return false;
+}
+
+/**
+ * Verify payment token
+ */
+async function verifyToken(token, apiKey) {
+  try {
+    const res = await fetch(`${TOLL_API_BASE}/api/verify`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Publisher-Key': apiKey,
+      },
+      body: JSON.stringify({ token }),
+    });
+    const data = await res.json();
+    return data.valid === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build 402 Payment Required response for agents
+ * Includes onboarding info for non-x402 capable agents
+ */
+function build402Response(req, options) {
+  const { apiKey, amount, resource } = options;
+  const requestedUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
+  const isX402Capable = req.headers['x-402-capable'] === 'true';
+  
+  const paymentInfo = {
+    status: 402,
+    message: 'Payment Required',
+    agent_instructions: `To access this resource, pay ${amount} USDC via the payment URL below. After payment, retry with the returned token in Authorization header.`,
+    payment: {
+      amount: amount,
+      currency: 'USDC',
+      network: 'solana',
+      pay_url: `${TOLL_API_BASE}/pay?publisher=${apiKey}&amount=${amount}&resource=${encodeURIComponent(requestedUrl)}`,
+      api_endpoint: `${TOLL_API_BASE}/api/pay`,
+    },
+    x402: {
+      version: 1,
+      amount: amount,
+      currency: 'USDC',
+      receiver: options.walletAddress || 'pending',
+      network: 'solana-mainnet',
+      description: `Access to ${resource || requestedUrl}`,
+    },
+    retry: {
+      method: req.method,
+      url: requestedUrl,
+      headers: {
+        'Authorization': 'Bearer <token_from_payment>',
+      },
+    },
+  };
+
+  // Add onboarding info for non-x402 capable agents
+  if (!isX402Capable) {
+    paymentInfo.x402_onboarding = {
+      message: "Your agent doesn't appear to have x402 payment capability configured. Here's how to enable it:",
+      what_is_x402: "x402 is a protocol that allows AI agents to make micropayments to access premium content and APIs autonomously.",
+      setup_steps: [
+        "1. Add the 'pay_toll' tool to your agent's tool configuration",
+        "2. Configure a Solana wallet with USDC for payments",
+        "3. Set budget limits for autonomous spending",
+        "4. Add 'x-402-capable: true' header to advertise capability"
+      ],
+      tool_schema: {
+        name: "pay_toll",
+        description: "Pay a micropayment toll to access a paywalled resource. Use when you encounter HTTP 402 Payment Required responses.",
+        parameters: {
+          type: "object",
+          required: ["pay_url", "amount"],
+          properties: {
+            pay_url: { type: "string", description: "The payment URL from the 402 response" },
+            amount: { type: "number", description: "Payment amount in USDC" },
+            max_amount: { type: "number", description: "Maximum you're willing to pay (safety limit)" }
+          }
+        }
+      },
+      example_tool_call: {
+        tool: "pay_toll",
+        arguments: {
+          pay_url: paymentInfo.payment.pay_url,
+          amount: amount,
+          max_amount: 0.05
+        }
+      },
+      documentation: `${TOLL_API_BASE}/docs#agent-setup`,
+      sdk_install: "npm install @agenttoll/sdk",
+      sample_integration: `${TOLL_API_BASE}/docs#pay-toll-tool`,
+      operator_dashboard: `${TOLL_API_BASE}/dashboard`,
+      support: "support@agenttoll.io"
+    };
+  }
+
+  return paymentInfo;
+}
+
+/**
+ * Express/Connect middleware factory
+ * 
+ * @param {string} apiKey - Your publisher API key from toll.agenttoll.io
+ * @param {object} options - Configuration options
+ * @returns {function} Express middleware
+ * 
+ * @example
+ * // One line integration
+ * app.use(tollbooth('pk_live_xxx'));
+ * 
+ * @example
+ * // With options
+ * app.use(tollbooth('pk_live_xxx', { 
+ *   amount: 0.01,
+ *   paths: ['/api/premium/*'],
+ *   freeForHumans: true 
+ * }));
+ */
+function tollbooth(apiKey, options = {}) {
+  const config = {
+    amount: options.amount || 0.005,
+    paths: options.paths || ['*'],
+    freeForHumans: options.freeForHumans ?? false,
+    walletAddress: options.walletAddress || null,
+    onPayment: options.onPayment || null,
+    bypassHeader: options.bypassHeader || null,
+  };
+
+  return async function tollboothMiddleware(req, res, next) {
+    // Check bypass header (for internal services)
+    if (config.bypassHeader && req.headers[config.bypassHeader.toLowerCase()]) {
+      return next();
+    }
+
+    // Check if path should be tolled
+    const shouldToll = config.paths.some(pattern => {
+      if (pattern === '*') return true;
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+      return regex.test(req.path);
+    });
+
+    if (!shouldToll) return next();
+
+    // Detect if agent
+    const agentRequest = isAgent(req);
+
+    // If free for humans and not an agent, pass through
+    if (config.freeForHumans && !agentRequest) {
+      return next();
+    }
+
+    // Check for existing payment token
+    const authHeader = req.headers['authorization'] || '';
+    const token = authHeader.replace(/^Bearer\s+/i, '');
+
+    if (token) {
+      const valid = await verifyToken(token, apiKey);
+      if (valid) {
+        // Track successful access
+        req.tollPaid = true;
+        req.tollAgent = agentRequest;
+        return next();
+      }
+    }
+
+    // No valid token - return 402 Payment Required
+    const paymentInfo = build402Response(req, {
+      apiKey,
+      amount: config.amount,
+      resource: req.path,
+      walletAddress: config.walletAddress,
+    });
+
+    // Check if agent advertises x402 capability
+    const isX402Capable = req.headers['x-402-capable'] === 'true';
+
+    // Set x402 headers for agent parsing
+    res.setHeader('X-402-Version', '1');
+    res.setHeader('X-402-Amount', config.amount.toString());
+    res.setHeader('X-402-Currency', 'USDC');
+    res.setHeader('X-402-Pay-URL', paymentInfo.payment.pay_url);
+    res.setHeader('X-402-Network', 'solana');
+    res.setHeader('Content-Type', 'application/json');
+    
+    // Add onboarding hint for non-capable agents
+    if (!isX402Capable) {
+      res.setHeader('X-402-Onboarding', 'true');
+      res.setHeader('X-402-Setup-URL', `${TOLL_API_BASE}/docs#agent-setup`);
+    }
+
+    return res.status(402).json(paymentInfo);
+  };
+}
+
+/**
+ * Protect specific routes (alternative API)
+ * 
+ * @example
+ * app.get('/premium', tollbooth.protect('pk_xxx', { amount: 0.01 }), handler)
+ */
+tollbooth.protect = function(apiKey, options = {}) {
+  return tollbooth(apiKey, { ...options, paths: ['*'] });
+};
+
+/**
+ * Agent-only tollbooth (humans pass free)
+ * 
+ * @example
+ * app.use(tollbooth.agentsOnly('pk_xxx'))
+ */
+tollbooth.agentsOnly = function(apiKey, options = {}) {
+  return tollbooth(apiKey, { ...options, freeForHumans: true });
+};
+
+/**
+ * Check if request has valid toll payment
+ */
+tollbooth.hasPaid = function(req) {
+  return req.tollPaid === true;
+};
+
+/**
+ * Check if request is from an agent
+ */
+tollbooth.isAgent = isAgent;
+
+// Export for different module systems
+module.exports = tollbooth;
+module.exports.default = tollbooth;
+module.exports.tollbooth = tollbooth;
+module.exports.isAgent = isAgent;