toll402-client 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# toll402-client
+
+One-line access to [Toll402](https://toll402.dev): pay-per-call tools for AI agents over x402 (USDC on Base).
+No API keys. Without a wallet you get the free trial (cheap tools, per-IP daily quota); with a wallet every call pays itself.
+
+```bash
+npm i toll402-client
+```
+
+```ts
+import { Toll402 } from "toll402-client";
+
+const t = new Toll402({ walletKey: process.env.WALLET_KEY as `0x${string}` }); // omit walletKey → free trial
+
+await t.read("https://example.com");                                   // page → clean Markdown ($0.002)
+await t.do("convert 100 usd to mxn", { base: "USD", quote: "MXN", amount: 100 }); // router: best tool, runs it
+await t.provenance("https://some-article");                            // human or synthetic? evidence + score
+await t.lookup("HTTP 402", { sources: ["wikipedia", "wikidata"] });    // trusted sources with citations
+await t.business.search({ city: "Ciudad de México", category: "dentist", minLevel: "corroborated" });
+await t.call("hn_top", { n: 5 });                                      // any catalog tool by name
+await t.forge({ name: "reverse_text", description: "...", inputSchema: {...}, examples: [...] }); // new tool for everyone
+
+t.lastPayment;     // decoded settlement of the last paid call (tx hash on Base)
+t.trialRemaining;  // free-trial calls left today (no wallet)
+```
+
+Errors throw `Toll402Error` with `status`, `code` (`payment_required`, `invalid_input`, `tool_failed`, …) and `price` when known.
+You are charged only on 2xx.
+
+## LangChain
+
+```ts
+import { toll402Tools } from "toll402-client/langchain";
+const tools = await toll402Tools(t, { maxPriceUsd: 0.05 });   // DynamicStructuredTool[] from the live catalog
+```
+
+## Vercel AI SDK
+
+```ts
+import { toll402AiTools } from "toll402-client/ai";
+const tools = await toll402AiTools(t, { kinds: ["builtin", "forged"] });
+await generateText({ model, tools, prompt: "Find verified dentists in Mexico City and summarize the top 3" });
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `walletKey` | — | 0x private key holding USDC on Base. Never hard-code it. |
+| `baseUrl` | `https://toll402.dev` | Self-hosted gateway URL |
+| `maxUsdPerCall` | `0.25` | Hard spend cap per payment |
+| `network` | `eip155:8453` | CAIP-2 network to pay on |
+
+Docs for machines: https://toll402.dev/llms.txt · Catalog: https://toll402.dev/v1/catalog · MIT.

package/dist/ai.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Vercel AI SDK adapter: every available Toll402 tool as an AI SDK `tool()`.
+ *   import { toll402AiTools } from "toll402-client/ai";
+ *   const tools = await toll402AiTools(new Toll402({ walletKey }));
+ *   generateText({ model, tools, prompt })
+ */
+import { type ToolSet } from "ai";
+import type { Toll402, CatalogTool } from "./index.js";
+export interface Toll402AiToolsOptions {
+    kinds?: ("builtin" | "forged" | "external")[];
+    maxPriceUsd?: number;
+    include?: (t: CatalogTool) => boolean;
+}
+export declare function toll402AiTools(client: Toll402, opts?: Toll402AiToolsOptions): Promise<ToolSet>;

package/dist/ai.js

@@ -0,0 +1,27 @@
+/**
+ * Vercel AI SDK adapter: every available Toll402 tool as an AI SDK `tool()`.
+ *   import { toll402AiTools } from "toll402-client/ai";
+ *   const tools = await toll402AiTools(new Toll402({ walletKey }));
+ *   generateText({ model, tools, prompt })
+ */
+import { tool, jsonSchema } from "ai";
+export async function toll402AiTools(client, opts = {}) {
+    const cat = await client.catalog();
+    const kinds = new Set(opts.kinds ?? ["builtin", "forged", "external"]);
+    const out = {};
+    for (const t of cat.tools) {
+        if (!t.available || !kinds.has(t.kind))
+            continue;
+        if (opts.maxPriceUsd !== undefined && t.priceUsd > opts.maxPriceUsd)
+            continue;
+        if (opts.include && !opts.include(t))
+            continue;
+        const name = t.name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+        out[name] = tool({
+            description: `${t.description} (Toll402 ${t.kind} tool, ${t.price} per call, paid automatically in USDC via x402)`,
+            parameters: jsonSchema(t.inputSchema),
+            execute: async (input) => client.call(t.path, input),
+        });
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+export interface Toll402Options {
+    /** 0x-prefixed private key of a wallet holding USDC on Base. Omit to use the free trial (cheap tools, per-IP quota). */
+    walletKey?: `0x${string}`;
+    /** Gateway URL. Default https://toll402.dev */
+    baseUrl?: string;
+    /** Hard cap per single payment in USD. Default 0.25 */
+    maxUsdPerCall?: number;
+    /** CAIP-2 network to pay on. Default "eip155:8453" (Base). Use "eip155:*" to accept any EVM network the server offers. */
+    network?: string;
+    /** Custom fetch (tests, polyfills). */
+    fetch?: typeof fetch;
+}
+export interface CatalogTool {
+    id: string;
+    kind: "builtin" | "forged" | "external";
+    name: string;
+    description: string;
+    tags: string[];
+    method: string;
+    path: string;
+    url: string;
+    price: string;
+    priceUsd: number;
+    available: boolean;
+    inputSchema: Record<string, unknown>;
+    example?: unknown;
+    outputExample?: unknown;
+    meta?: Record<string, unknown>;
+}
+export interface Catalog {
+    service: string;
+    version: string;
+    description: string;
+    baseUrl: string;
+    payment: Record<string, unknown>;
+    counts: {
+        builtin: number;
+        forged: number;
+        external: number;
+    };
+    freeTrial?: {
+        callsPerIpPerDay: number;
+        toolsPricedUpTo: string;
+        note: string;
+    } | null;
+    tools: CatalogTool[];
+}
+export interface PaymentInfo {
+    success: boolean;
+    transaction?: string;
+    network?: string;
+    payer?: string;
+    [k: string]: unknown;
+}
+export declare class Toll402Error extends Error {
+    status: number;
+    code: string;
+    price?: string | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, status: number, code: string, price?: string | undefined, details?: unknown | undefined);
+}
+export interface ForgeSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    examples: {
+        input: Record<string, unknown>;
+        expectedOutput?: unknown;
+    }[];
+    allowNetwork?: boolean;
+    priceUsd?: number;
+    tags?: string[];
+    creator?: string;
+}
+export declare class Toll402 {
+    readonly baseUrl: string;
+    readonly address?: string;
+    /** Decoded PAYMENT-RESPONSE of the last paid call (undefined for free/trial calls). */
+    lastPayment?: PaymentInfo;
+    /** Remaining free-trial calls reported by the server on the last call (undefined once you pay). */
+    trialRemaining?: number;
+    private readonly f;
+    private catalogCache?;
+    constructor(opts?: Toll402Options);
+    catalog(opts?: {
+        fresh?: boolean;
+    }): Promise<Catalog>;
+    /** Free: ranked tools for a plain-language need. */
+    find(need: string, opts?: {
+        limit?: number;
+        kinds?: ("builtin" | "forged" | "external")[];
+    }): Promise<{
+        matches: (CatalogTool & {
+            score: number;
+        })[];
+        forgeHint?: string;
+    }>;
+    /** Call any tool by catalog name ("read_url", "hn_top", …), id ("t/hn_top", "x/abc123") or path ("/v1/read"). Returns the tool's `result`. */
+    call<T = unknown>(tool: string, input?: Record<string, unknown>): Promise<T>;
+    /** One endpoint for everything: routes `need` to the best tool and runs it with `input`. */
+    do<T = unknown>(need: string, input: Record<string, unknown>, opts?: {
+        maxPriceUsd?: number;
+        tool?: string;
+    }): Promise<{
+        executed: boolean;
+        tool?: {
+            id: string;
+            name: string;
+            price: string;
+        };
+        result?: T;
+        reason?: string;
+        alternatives?: unknown[];
+    }>;
+    /** Create a new tool from a description + examples; published for every agent on success. */
+    forge(spec: ForgeSpec): Promise<{
+        published: boolean;
+        tool?: {
+            name: string;
+            url: string;
+            price: string;
+        };
+        attempts: number;
+        results: unknown[];
+        notes?: string;
+    }>;
+    read(url: string, opts?: {
+        format?: "markdown" | "text" | "both";
+        includeLinks?: boolean;
+        maxChars?: number;
+    }): Promise<{
+        url: string;
+        title: string | null;
+        markdown?: string;
+        text?: string;
+        wordCount: number;
+        links?: {
+            text: string;
+            href: string;
+        }[];
+    }>;
+    provenance(url: string, opts?: {
+        deep?: boolean;
+    }): Promise<{
+        humanOriginScore: number;
+        verdict: string;
+        confidence: number;
+        evidence: unknown[];
+        firstArchived: string | null;
+    }>;
+    lookup(query: string, opts?: {
+        language?: string;
+        sources?: string[];
+        maxPassages?: number;
+        synthesize?: boolean;
+    }): Promise<{
+        answer: {
+            text: string;
+            citations: number[];
+            confidence: number;
+        } | null;
+        passages: unknown[];
+    }>;
+    extract<T = unknown>(input: {
+        url?: string;
+        text?: string;
+        schema: Record<string, unknown>;
+        instructions?: string;
+    }): Promise<{
+        data: T;
+        source: string | null;
+    }>;
+    summarize(input: {
+        url?: string;
+        text?: string;
+        style?: "bullets" | "paragraph" | "tldr" | "detailed";
+        maxWords?: number;
+        language?: string;
+        focus?: string;
+    }): Promise<{
+        summary: string;
+        title: string | null;
+    }>;
+    judge(input: {
+        task: string;
+        candidate: string;
+        reference?: string;
+        criteria?: string[];
+    }): Promise<{
+        overall: number;
+        pass: boolean;
+        scores: unknown[];
+        issues: string[];
+        suggestions: string[];
+    }>;
+    verifyEmail(email: string): Promise<{
+        valid: boolean;
+        score: number;
+        disposable: boolean;
+        roleAccount: boolean;
+    }>;
+    fx(base: string, quote?: string, amount?: number): Promise<{
+        base: string;
+        quote?: string;
+        rate?: number;
+        converted?: number;
+        rates?: Record<string, number>;
+        date: string;
+    }>;
+    /** Verified business directory. */
+    readonly business: {
+        search: (q: {
+            query?: string;
+            category?: string;
+            city?: string;
+            cityKey?: string;
+            country?: string;
+            near?: {
+                lat: number;
+                lon: number;
+                radiusKm?: number;
+            };
+            minScore?: number;
+            minLevel?: string;
+            claimedOnly?: boolean;
+            includeEvidence?: boolean;
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            total: number;
+            items: unknown[];
+            region?: unknown;
+        }>;
+        verify: (q: {
+            id?: string;
+            name?: string;
+            website?: string;
+            phone?: string;
+            address?: string;
+            city?: string;
+            country?: string;
+        }) => Promise<{
+            inDirectory: boolean;
+            matches: unknown[];
+            liveChecks: {
+                score: number;
+                level: string;
+                evidence: unknown[];
+            };
+            verdict: string;
+        }>;
+        details: (id: string, opts?: {
+            force?: boolean;
+        }) => Promise<{
+            business: unknown;
+            enrichment: unknown;
+            cached: boolean;
+        }>;
+        /** Free public profile. */
+        get: (id: string) => Promise<Record<string, unknown>>;
+    };
+    private resolvePath;
+}
+export default Toll402;

package/dist/index.js

@@ -0,0 +1,158 @@
+/**
+ * toll402-client — one-line access to Toll402 (https://toll402.dev):
+ * pay-per-call tools for AI agents over x402 (USDC on Base).
+ *
+ *   const t = new Toll402({ walletKey: process.env.WALLET_KEY });   // or no key → free trial
+ *   await t.read("https://example.com");
+ *   await t.do("convert 100 usd to mxn", { base: "USD", quote: "MXN", amount: 100 });
+ */
+import { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+export class Toll402Error extends Error {
+    status;
+    code;
+    price;
+    details;
+    constructor(message, status, code, price, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.price = price;
+        this.details = details;
+        this.name = "Toll402Error";
+    }
+}
+export class Toll402 {
+    baseUrl;
+    address;
+    /** Decoded PAYMENT-RESPONSE of the last paid call (undefined for free/trial calls). */
+    lastPayment;
+    /** Remaining free-trial calls reported by the server on the last call (undefined once you pay). */
+    trialRemaining;
+    f;
+    catalogCache;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? "https://toll402.dev").replace(/\/$/, "");
+        const base = opts.fetch ?? globalThis.fetch;
+        if (opts.walletKey) {
+            const account = privateKeyToAccount(opts.walletKey);
+            this.address = account.address;
+            this.f = wrapFetchWithPaymentFromConfig(base, {
+                schemes: [{ network: (opts.network ?? "eip155:8453"), client: new ExactEvmScheme(account) }],
+                spendControls: { maxAmountPerPayment: `$${opts.maxUsdPerCall ?? 0.25}` },
+            });
+        }
+        else {
+            this.f = base;
+        }
+    }
+    // ---- discovery (free) ------------------------------------------------------
+    async catalog(opts = {}) {
+        if (!opts.fresh && this.catalogCache && Date.now() - this.catalogCache.at < 5 * 60_000)
+            return this.catalogCache.data;
+        const r = await this.f(`${this.baseUrl}/v1/catalog`);
+        if (!r.ok)
+            throw new Toll402Error(`catalog: HTTP ${r.status}`, r.status, "catalog_unavailable");
+        const data = (await r.json());
+        this.catalogCache = { at: Date.now(), data };
+        return data;
+    }
+    /** Free: ranked tools for a plain-language need. */
+    async find(need, opts = {}) {
+        const r = await this.f(`${this.baseUrl}/v1/find`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ need, ...opts }) });
+        const j = (await r.json());
+        if (!r.ok)
+            throw new Toll402Error(`find: HTTP ${r.status}`, r.status, "find_failed", undefined, j);
+        return j;
+    }
+    // ---- calls (paid; free trial when no wallet) ----------------------------------
+    /** Call any tool by catalog name ("read_url", "hn_top", …), id ("t/hn_top", "x/abc123") or path ("/v1/read"). Returns the tool's `result`. */
+    async call(tool, input = {}) {
+        const path = await this.resolvePath(tool);
+        const r = await this.f(`${this.baseUrl}${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(input) });
+        const trial = r.headers.get("x-toll402-trial-remaining");
+        this.trialRemaining = trial !== null ? Number(trial) : undefined;
+        const pr = r.headers.get("payment-response") ?? r.headers.get("x-payment-response");
+        if (pr) {
+            try {
+                this.lastPayment = decodePaymentResponseHeader(pr);
+            }
+            catch {
+                /* ignore undecodable header */
+            }
+        }
+        const text = await r.text();
+        let body = {};
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = { raw: text };
+        }
+        if (r.status === 402) {
+            throw new Toll402Error(body.message ?? "Payment required: configure walletKey with USDC on Base (or your free-trial quota is exhausted)", 402, "payment_required", body.price, body);
+        }
+        if (!r.ok || body.ok === false) {
+            throw new Toll402Error(body.message ?? `HTTP ${r.status}`, r.status, body.error ?? "error", undefined, body);
+        }
+        return body.result;
+    }
+    /** One endpoint for everything: routes `need` to the best tool and runs it with `input`. */
+    async do(need, input, opts = {}) {
+        return this.call("/v1/do", { need, input, ...opts });
+    }
+    /** Create a new tool from a description + examples; published for every agent on success. */
+    forge(spec) {
+        return this.call("/v1/forge", spec);
+    }
+    read(url, opts = {}) {
+        return this.call("/v1/read", { url, ...opts });
+    }
+    provenance(url, opts = {}) {
+        return this.call("/v1/provenance", { url, ...opts });
+    }
+    lookup(query, opts = {}) {
+        return this.call("/v1/lookup", { query, ...opts });
+    }
+    extract(input) {
+        return this.call("/v1/extract", input);
+    }
+    summarize(input) {
+        return this.call("/v1/summarize", input);
+    }
+    judge(input) {
+        return this.call("/v1/judge", input);
+    }
+    verifyEmail(email) {
+        return this.call("/v1/email/verify", { email });
+    }
+    fx(base, quote, amount = 1) {
+        return this.call("/v1/fx", { base, quote, amount });
+    }
+    /** Verified business directory. */
+    business = {
+        search: (q) => this.call("/v1/biz/search", q),
+        verify: (q) => this.call("/v1/biz/verify", q),
+        details: (id, opts = {}) => this.call("/v1/biz/details", { id, ...opts }),
+        /** Free public profile. */
+        get: async (id) => {
+            const r = await this.f(`${this.baseUrl}/v1/biz/${encodeURIComponent(id)}`);
+            if (!r.ok)
+                throw new Toll402Error(`business ${id}: HTTP ${r.status}`, r.status, "not_found");
+            return r.json();
+        },
+    };
+    async resolvePath(tool) {
+        if (tool.startsWith("/"))
+            return tool;
+        if (tool.startsWith("t/") || tool.startsWith("x/"))
+            return `/v1/${tool}`;
+        const cat = await this.catalog();
+        const hit = cat.tools.find((t) => t.name === tool || t.id === tool);
+        if (!hit)
+            throw new Toll402Error(`Unknown tool "${tool}". Use find() to discover tools.`, 404, "unknown_tool");
+        return hit.path;
+    }
+}
+export default Toll402;

package/dist/langchain.d.ts

@@ -0,0 +1,25 @@
+/**
+ * LangChain adapter: every available Toll402 tool as a DynamicStructuredTool.
+ *   import { toll402Tools } from "toll402-client/langchain";
+ *   const tools = await toll402Tools(new Toll402({ walletKey }));
+ */
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { z } from "zod";
+import type { Toll402, CatalogTool } from "./index.js";
+/** Minimal JSON-Schema → zod conversion (objects with string/number/integer/boolean/array/object props, enums, optional). */
+export declare function jsonSchemaToZod(schema: Record<string, unknown>): z.ZodTypeAny;
+export interface Toll402ToolsOptions {
+    /** Only these kinds (default: builtin + forged; external excluded unless proxied/available). */
+    kinds?: ("builtin" | "forged" | "external")[];
+    /** Skip tools priced above this (USD). */
+    maxPriceUsd?: number;
+    /** Filter by name/id. */
+    include?: (t: CatalogTool) => boolean;
+}
+export declare function toll402Tools(client: Toll402, opts?: Toll402ToolsOptions): Promise<DynamicStructuredTool<z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny, {
+    [x: string]: any;
+}, {
+    [x: string]: any;
+}>, Record<string, unknown>, {
+    [x: string]: any;
+}, string>[]>;

package/dist/langchain.js

@@ -0,0 +1,51 @@
+/**
+ * LangChain adapter: every available Toll402 tool as a DynamicStructuredTool.
+ *   import { toll402Tools } from "toll402-client/langchain";
+ *   const tools = await toll402Tools(new Toll402({ walletKey }));
+ */
+import { DynamicStructuredTool } from "@langchain/core/tools";
+import { z } from "zod";
+/** Minimal JSON-Schema → zod conversion (objects with string/number/integer/boolean/array/object props, enums, optional). */
+export function jsonSchemaToZod(schema) {
+    const type = schema.type;
+    if (schema.enum && Array.isArray(schema.enum))
+        return z.enum(schema.enum.map(String));
+    switch (type) {
+        case "string":
+            return z.string();
+        case "number":
+            return z.number();
+        case "integer":
+            return z.number().int();
+        case "boolean":
+            return z.boolean();
+        case "array":
+            return z.array(schema.items ? jsonSchemaToZod(schema.items) : z.unknown());
+        case "object": {
+            const props = schema.properties ?? {};
+            const required = new Set(schema.required ?? []);
+            const shape = {};
+            for (const [k, v] of Object.entries(props)) {
+                let zz = jsonSchemaToZod(v);
+                if (typeof v.description === "string")
+                    zz = zz.describe(v.description);
+                shape[k] = required.has(k) ? zz : zz.optional();
+            }
+            return Object.keys(shape).length ? z.object(shape).passthrough() : z.record(z.unknown());
+        }
+        default:
+            return z.unknown();
+    }
+}
+export async function toll402Tools(client, opts = {}) {
+    const cat = await client.catalog();
+    const kinds = new Set(opts.kinds ?? ["builtin", "forged", "external"]);
+    return cat.tools
+        .filter((t) => t.available && kinds.has(t.kind) && (opts.maxPriceUsd === undefined || t.priceUsd <= opts.maxPriceUsd) && (opts.include?.(t) ?? true))
+        .map((t) => new DynamicStructuredTool({
+        name: t.name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64),
+        description: `${t.description} (Toll402 ${t.kind} tool, ${t.price} per call, paid automatically in USDC via x402)`,
+        schema: jsonSchemaToZod(t.inputSchema),
+        func: async (input) => JSON.stringify(await client.call(t.path, input)),
+    }));
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "toll402-client",
+  "version": "0.1.0",
+  "description": "One-line client for Toll402 — pay-per-call tools for AI agents via x402 (USDC on Base). Free trial without a wallet; automatic payment with one.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://toll402.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/toll402/toll402",
+    "directory": "clients/js"
+  },
+  "keywords": [
+    "x402",
+    "ai-agents",
+    "tools",
+    "usdc",
+    "base",
+    "langchain",
+    "vercel-ai",
+    "mcp"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.js"
+    },
+    "./ai": {
+      "types": "./dist/ai.d.ts",
+      "import": "./dist/ai.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "smoke": "tsx src/__smoke__.ts"
+  },
+  "dependencies": {
+    "@x402/evm": "~2.25.0",
+    "@x402/fetch": "~2.25.0",
+    "viem": "^2.56.3"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3.0",
+    "ai": ">=4.0.0",
+    "zod": ">=3.23.0"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@langchain/core": "^0.3.0",
+    "@types/node": "^22",
+    "ai": "^4.0.0",
+    "tsx": "^4.23.13",
+    "typescript": "^5.7.0",
+    "zod": "^3.24.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}