agent-toll-sdk

Public SDK for agent runtimes calling Agent-Toll–protected HTTPS APIs. Handles 402 Payment Required, on-chain USDC transfers on Base (publisher + fixed 5% commission), retries, and signed receipt caching.

Install

npm install agent-toll-sdk

Quick start

Each publisher runs their own middleware at a base URL. Point baseUrl at that host (not at the central dashboard).

const { AgentClient } = require('agent-toll-sdk');

const client = new AgentClient({
  wallet: process.env.AGENT_PRIVATE_KEY,
  rpcUrl: process.env.BASE_RPC_URL,
  baseUrl: process.env.BASE_URL,
  trustedSignerAddress: process.env.RECEIPT_SIGNER_ADDRESS
});

const article = await client.get('/article/123');

• baseUrl: https://publisher-example.com (or http://localhost:3000 in dev).
• trustedSignerAddress: optional if you learn the signer from the first 402 response (signer_address); recommended in production.

Multi-publisher (many sites)

• One AgentClient per publisher origin. Receipts and payment challenges are scoped to that host’s paths.
• Example: Site A and Site B each deploy middleware → agents use two clients or switch baseUrl per task.

const siteA = new AgentClient({ wallet, rpcUrl, baseUrl: 'https://a.example.com' });
const siteB = new AgentClient({ wallet, rpcUrl, baseUrl: 'https://b.example.com' });

The central platform (optional) aggregates metrics from many publishers via PUBLISHERS_JSON; that is separate from the agent SDK.

Features

• Automatic 402 → pay → retry with X-Agent-Payment-Tx and X-Agent-Commission-Tx
• Receipt signature verification before cache/reuse
• Per-scope receipt cache (TTL from middleware)
• Exponential backoff for transient failures
• Split USDC payments (publisher amount + 5% commission)

Documentation

• Full deployment guide (publishers + platform + env): see CUSTOMER_DEPLOYMENT_GUIDE.md in the Agent-Toll repository (or your vendor’s doc mirror).
• If you operate the central dashboard, developer docs are also served at GET /docs on the platform.

Publish (maintainers)

cd sdk
npm publish --access=public

If the unscoped name is unavailable on npm, publish under a scope (e.g. @yourcompany/agent-toll-sdk) and update the name field in package.json.