@mcpaid/sdk 2.0.0

package/dist/gateway/toolpay-gateway.js

@@ -0,0 +1,320 @@
+/**
+ * ToolPay Gateway Engine
+ * Reverse proxy interceptor for Model Context Protocol (MCP) JSON-RPC requests.
+ */
+import { usdToMicro, microToUsd } from '../utils/units.js';
+import { canonicalJsonStringify } from '../utils/units.js';
+export class ToolPayGateway {
+    registry;
+    orchestrator;
+    circuitBreaker;
+    upstreamHandler;
+    // Freemium usage tracking: `${serverId}:${toolName}:${agentWallet}:${periodBucket}` -> callCount
+    freemiumUsage = new Map();
+    // Scoped Idempotency cache: scopedKey -> cached GatewayResponse
+    idempotencyCache = new Map();
+    constructor(params) {
+        this.registry = params.registry;
+        this.orchestrator = params.orchestrator;
+        this.circuitBreaker = params.circuitBreaker;
+        this.upstreamHandler = params.upstreamHandler;
+        if (params.idempotencyCache) {
+            this.idempotencyCache = params.idempotencyCache;
+        }
+        if (params.freemiumUsage) {
+            this.freemiumUsage = params.freemiumUsage;
+        }
+    }
+    /**
+     * Main entry point to handle an incoming MCP JSON-RPC request.
+     */
+    async handleRequest(request, context) {
+        const serverConfig = this.registry.getServer(context.serverId);
+        if (!serverConfig) {
+            return {
+                statusCode: 404,
+                headers: { 'Content-Type': 'application/json' },
+                body: {
+                    jsonrpc: '2.0',
+                    id: request.id ?? null,
+                    error: {
+                        code: -32000,
+                        message: `Server "${context.serverId}" not found in ToolPay registry`,
+                    },
+                },
+            };
+        }
+        // Scoped idempotency key prevents cross-server / cross-tenant cache poisoning (Finding 7)
+        const scopedIdempotencyKey = context.idempotencyKey
+            ? `${context.serverId}:${context.agentWallet || 'anon'}:${request.method}:${canonicalJsonStringify(request.params || {})}:${context.idempotencyKey}`
+            : undefined;
+        if (scopedIdempotencyKey && this.idempotencyCache.has(scopedIdempotencyKey)) {
+            return this.idempotencyCache.get(scopedIdempotencyKey);
+        }
+        // 1. Intercept tools/list
+        if (request.method === 'tools/list') {
+            return this.handleToolsList(request, serverConfig);
+        }
+        // 2. Intercept tools/call
+        if (request.method === 'tools/call') {
+            const response = await this.handleToolsCall(request, serverConfig, context);
+            if (scopedIdempotencyKey && response.statusCode === 200) {
+                if (this.idempotencyCache.size >= 5_000) {
+                    const iter = this.idempotencyCache.keys();
+                    for (let i = 0; i < 50; i++) {
+                        const next = iter.next();
+                        if (next.done)
+                            break;
+                        this.idempotencyCache.delete(next.value);
+                    }
+                }
+                this.idempotencyCache.set(scopedIdempotencyKey, response);
+            }
+            return response;
+        }
+        // 3. Transparently pass through all other MCP methods (initialize, ping, resources/*, prompts/*)
+        const upstreamRes = await this.upstreamHandler(request);
+        return {
+            statusCode: 200,
+            headers: { 'Content-Type': 'application/json' },
+            body: upstreamRes,
+        };
+    }
+    /**
+     * Handles `tools/list`, enriching tools with payment metadata annotations.
+     */
+    async handleToolsList(request, serverConfig) {
+        const upstreamRes = await this.upstreamHandler(request);
+        if (upstreamRes.result && Array.isArray(upstreamRes.result.tools)) {
+            const listResult = upstreamRes.result;
+            const enrichedTools = listResult.tools.map((tool) => {
+                const rule = this.registry.getToolRule(serverConfig.serverId, tool.name);
+                const isPaid = rule?.type === 'fixed' || rule?.type === 'dynamic';
+                return {
+                    ...tool,
+                    annotations: {
+                        ...tool.annotations,
+                        payment: {
+                            required: isPaid,
+                            costUsd: rule?.type === 'fixed' ? rule.priceUsd : undefined,
+                            currency: serverConfig.currency,
+                            networks: [serverConfig.network],
+                            description: rule?.description || (isPaid ? `Pay-per-use tool ($${rule?.priceUsd || 'variable'})` : 'Free tool'),
+                        },
+                    },
+                };
+            });
+            return {
+                statusCode: 200,
+                headers: { 'Content-Type': 'application/json' },
+                body: {
+                    jsonrpc: '2.0',
+                    id: request.id ?? null,
+                    result: {
+                        ...listResult,
+                        tools: enrichedTools,
+                    },
+                },
+            };
+        }
+        return {
+            statusCode: 200,
+            headers: { 'Content-Type': 'application/json' },
+            body: upstreamRes,
+        };
+    }
+    /**
+     * Handles `tools/call`, checking pricing, circuit breakers, and payment verification.
+     */
+    async handleToolsCall(request, serverConfig, context) {
+        const toolName = request.params?.name;
+        if (!toolName) {
+            return {
+                statusCode: 400,
+                headers: { 'Content-Type': 'application/json' },
+                body: {
+                    jsonrpc: '2.0',
+                    id: request.id ?? null,
+                    error: { code: -32602, message: 'Missing tool name in tools/call parameters' },
+                },
+            };
+        }
+        const toolRule = this.registry.getToolRule(serverConfig.serverId, toolName);
+        // If tool is explicitly free or unconfigured without default pricing
+        if (!toolRule || toolRule.type === 'free') {
+            const res = await this.upstreamHandler(request);
+            return {
+                statusCode: 200,
+                headers: { 'Content-Type': 'application/json' },
+                body: res,
+            };
+        }
+        const agentWallet = context.agentWallet || context.paymentProof?.signerWallet || '0x0000000000000000000000000000000000000000';
+        const nowSec = context.nowSec || Math.floor(Date.now() / 1000);
+        // Check freemium allowance if configured
+        if (toolRule.freemium && agentWallet !== '0x0000000000000000000000000000000000000000') {
+            const periodSec = toolRule.freemium.periodSeconds || 86400;
+            const periodBucket = Math.floor(nowSec / periodSec);
+            const usageKey = `${serverConfig.serverId}:${toolName}:${agentWallet.toLowerCase()}:${periodBucket}`;
+            const currentUsage = this.freemiumUsage.get(usageKey) || 0;
+            if (currentUsage < toolRule.freemium.freeCallsPerPeriod) {
+                this.freemiumUsage.set(usageKey, currentUsage + 1);
+                const res = await this.upstreamHandler(request);
+                return {
+                    statusCode: 200,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Freemium-Remaining': (toolRule.freemium.freeCallsPerPeriod - currentUsage - 1).toString(),
+                    },
+                    body: res,
+                };
+            }
+        }
+        // Resolve cost
+        let grossMicro;
+        if (toolRule.type === 'fixed') {
+            if (!toolRule.priceUsd) {
+                throw new Error(`Tool "${toolName}" configured as fixed price but missing priceUsd`);
+            }
+            grossMicro = usdToMicro(toolRule.priceUsd);
+        }
+        else if (toolRule.type === 'dynamic') {
+            if (!toolRule.dynamicPricing) {
+                throw new Error(`Tool "${toolName}" configured as dynamic price but missing dynamicPricing function`);
+            }
+            const dynamicPriceUsd = toolRule.dynamicPricing(request.params?.arguments || {});
+            grossMicro = usdToMicro(dynamicPriceUsd);
+        }
+        else {
+            grossMicro = 0n;
+        }
+        // If cost resolved to 0, execute free
+        if (grossMicro === 0n) {
+            const res = await this.upstreamHandler(request);
+            return {
+                statusCode: 200,
+                headers: { 'Content-Type': 'application/json' },
+                body: res,
+            };
+        }
+        // Circuit Breaker Evaluation
+        const cbConfig = toolRule.circuitBreaker || serverConfig.globalCircuitBreaker;
+        const cbCheck = this.circuitBreaker.check({
+            serverId: serverConfig.serverId,
+            toolName,
+            agentWallet,
+            costMicro: grossMicro,
+            callArguments: request.params?.arguments,
+            timestamp: nowSec * 1000,
+        }, cbConfig);
+        if (!cbCheck.allowed) {
+            const status = cbCheck.statusCode || 429;
+            return {
+                statusCode: status,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(cbCheck.retryAfterSeconds ? { 'Retry-After': cbCheck.retryAfterSeconds.toString() } : {}),
+                },
+                body: {
+                    jsonrpc: '2.0',
+                    id: request.id ?? null,
+                    error: {
+                        code: status,
+                        message: `ToolPay Circuit Breaker: ${cbCheck.reason}`,
+                        data: cbCheck,
+                    },
+                },
+            };
+        }
+        // Check for payment proof
+        if (!context.paymentProof) {
+            // Return HTTP 402 Challenge
+            const challenge = this.orchestrator.generateChallenge(serverConfig, toolRule, grossMicro);
+            return {
+                statusCode: 402,
+                headers: challenge.headers,
+                body: challenge.errorResponse.body,
+            };
+        }
+        // Settle payment proof with bound tool/price context (Critical 1)
+        const settlementResult = await this.orchestrator.verifyAndSettle(context.paymentProof, nowSec, {
+            serverId: serverConfig.serverId,
+            toolName,
+            minAmountMicro: grossMicro,
+        });
+        if (!settlementResult.success) {
+            // Include fresh challenge details so client can recover without dead-ending (High 8)
+            const challenge = this.orchestrator.generateChallenge(serverConfig, toolRule, grossMicro);
+            return {
+                statusCode: 402,
+                headers: challenge.headers,
+                body: {
+                    jsonrpc: '2.0',
+                    id: request.id ?? null,
+                    error: {
+                        code: 402,
+                        message: `Payment Verification Failed: ${settlementResult.error}`,
+                        data: challenge.errorResponse.body.error.data,
+                    },
+                },
+            };
+        }
+        // Commit spend to circuit breaker
+        this.circuitBreaker.commit({
+            serverId: serverConfig.serverId,
+            toolName,
+            agentWallet,
+            costMicro: grossMicro,
+            callArguments: request.params?.arguments,
+            timestamp: nowSec * 1000,
+        });
+        // Execute upstream tool call with refund safety (High 10)
+        let upstreamRes;
+        try {
+            upstreamRes = await this.upstreamHandler(request);
+            if (upstreamRes && upstreamRes.error && upstreamRes.error.code <= -32600) {
+                this.orchestrator.getLedger().refundTransaction(settlementResult.record.transactionId);
+                if (context.paymentProof.scheme === 'session-wallet' && context.paymentProof.sessionId) {
+                    this.orchestrator.sessionWalletManager.refundPayment({
+                        sessionId: context.paymentProof.sessionId,
+                        amountMicro: grossMicro,
+                    });
+                }
+            }
+        }
+        catch (err) {
+            this.orchestrator.getLedger().refundTransaction(settlementResult.record.transactionId);
+            if (context.paymentProof.scheme === 'session-wallet' && context.paymentProof.sessionId) {
+                this.orchestrator.sessionWalletManager.refundPayment({
+                    sessionId: context.paymentProof.sessionId,
+                    amountMicro: grossMicro,
+                });
+            }
+            return {
+                statusCode: 502,
+                headers: { 'Content-Type': 'application/json' },
+                body: {
+                    jsonrpc: '2.0',
+                    id: request.id ?? null,
+                    error: {
+                        code: -32000,
+                        message: `Upstream tool execution failed: ${err.message}. Micropayment refunded.`,
+                    },
+                },
+            };
+        }
+        // Return result with ToolPay settlement metadata in headers
+        return {
+            statusCode: 200,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-ToolPay-Transaction-Id': settlementResult.record.transactionId,
+                'X-ToolPay-Gross-Amount': microToUsd(settlementResult.record.grossAmountMicro),
+                'X-ToolPay-Platform-Fee': microToUsd(settlementResult.record.platformFeeMicro),
+                'X-ToolPay-Developer-Payout': microToUsd(settlementResult.record.developerPayoutMicro),
+            },
+            body: upstreamRes,
+        };
+    }
+}
+//# sourceMappingURL=toolpay-gateway.js.map

package/dist/gateway/toolpay-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolpay-gateway.js","sourceRoot":"","sources":["../../src/gateway/toolpay-gateway.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ToolPay: MCP Monetization & Micropayment Infrastructure
+ * Public Exports (client-only — see NPM_RESTRUCTURE.md)
+ *
+ * Operator modules (edge persistence, page renderers, relayer, mail) are
+ * intentionally NOT exported here: d1-store, dashboard/landing/docs HTML,
+ * withdrawal-relayer, email-service, worker. They remain in-repo for the
+ * hosted gateway but are excluded from the published tarball.
+ */
+export * from './types/mcp.js';
+export * from './types/pricing.js';
+export * from './types/x402.js';
+export * from './types/ledger.js';
+export * from './types/circuit-breaker.js';
+export * from './utils/units.js';
+export * from './fee/fee-calculator.js';
+export * from './fee/fee-ledger.js';
+export * from './circuit-breaker/circuit-breaker.js';
+export * from './settlement/nonce-store.js';
+export * from './settlement/permit-verifier.js';
+export * from './settlement/onchain-verifier.js';
+export * from './settlement/base-contract-client.js';
+export * from './settlement/session-wallet.js';
+export * from './settlement/payment-orchestrator.js';
+export * from './contracts/router-registry.js';
+export * from './gateway/server-registry.js';
+export * from './gateway/toolpay-gateway.js';
+export * from './gateway/config-loader.js';
+export * from './transports/sse-transport.js';
+export * from './transports/stdio-bridge.js';
+export * from './sdk/server-sdk.js';
+export * from './sdk/client-agent.js';
+export { ToolPayServer as MCPaidServer, ToolPayServer as McpaidServer, ToolPayServerOptions as MCPaidServerOptions, ToolPayServerOptions as McpaidServerOptions, } from './sdk/server-sdk.js';
+export { ToolPayClientAgent as MCPaidClientAgent, ToolPayClientAgent as McpaidClientAgent, ToolPayClientAgentOptions as MCPaidClientAgentOptions, ToolPayClientAgentOptions as McpaidClientAgentOptions, } from './sdk/client-agent.js';
+export { ToolPayGateway as MCPaidGateway, ToolPayGateway as McpaidGateway, ToolPayGatewayOptions as MCPaidGatewayOptions, ToolPayGatewayOptions as McpaidGatewayOptions, } from './gateway/toolpay-gateway.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,kBAAkB,CAAC;AAEjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,sCAAsC,CAAC;AAErD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC;AAE/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAE7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EACL,aAAa,IAAI,YAAY,EAC7B,aAAa,IAAI,YAAY,EAC7B,oBAAoB,IAAI,mBAAmB,EAC3C,oBAAoB,IAAI,mBAAmB,GAC5C,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,IAAI,iBAAiB,EACvC,kBAAkB,IAAI,iBAAiB,EACvC,yBAAyB,IAAI,wBAAwB,EACrD,yBAAyB,IAAI,wBAAwB,GACtD,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,IAAI,aAAa,EAC/B,cAAc,IAAI,aAAa,EAC/B,qBAAqB,IAAI,oBAAoB,EAC7C,qBAAqB,IAAI,oBAAoB,GAC9C,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * ToolPay: MCP Monetization & Micropayment Infrastructure
+ * Public Exports (client-only — see NPM_RESTRUCTURE.md)
+ *
+ * Operator modules (edge persistence, page renderers, relayer, mail) are
+ * intentionally NOT exported here: d1-store, dashboard/landing/docs HTML,
+ * withdrawal-relayer, email-service, worker. They remain in-repo for the
+ * hosted gateway but are excluded from the published tarball.
+ */
+export * from './types/mcp.js';
+export * from './types/pricing.js';
+export * from './types/x402.js';
+export * from './types/ledger.js';
+export * from './types/circuit-breaker.js';
+export * from './utils/units.js';
+export * from './fee/fee-calculator.js';
+export * from './fee/fee-ledger.js';
+export * from './circuit-breaker/circuit-breaker.js';
+export * from './settlement/nonce-store.js';
+export * from './settlement/permit-verifier.js';
+export * from './settlement/onchain-verifier.js';
+export * from './settlement/base-contract-client.js';
+export * from './settlement/session-wallet.js';
+export * from './settlement/payment-orchestrator.js';
+export * from './contracts/router-registry.js';
+export * from './gateway/server-registry.js';
+export * from './gateway/toolpay-gateway.js';
+export * from './gateway/config-loader.js';
+export * from './transports/sse-transport.js';
+export * from './transports/stdio-bridge.js';
+export * from './sdk/server-sdk.js';
+export * from './sdk/client-agent.js';
+// MCPaid Brand Aliases
+export { ToolPayServer as MCPaidServer, ToolPayServer as McpaidServer, } from './sdk/server-sdk.js';
+export { ToolPayClientAgent as MCPaidClientAgent, ToolPayClientAgent as McpaidClientAgent, } from './sdk/client-agent.js';
+export { ToolPayGateway as MCPaidGateway, ToolPayGateway as McpaidGateway, } from './gateway/toolpay-gateway.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,kBAAkB,CAAC;AAEjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,sCAAsC,CAAC;AAErD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC;AAE/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAE3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAE7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,uBAAuB;AACvB,OAAO,EACL,aAAa,IAAI,YAAY,EAC7B,aAAa,IAAI,YAAY,GAG9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,IAAI,iBAAiB,EACvC,kBAAkB,IAAI,iBAAiB,GAGxC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,IAAI,aAAa,EAC/B,cAAc,IAAI,aAAa,GAGhC,MAAM,8BAA8B,CAAC"}

package/dist/sdk/client-agent.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ToolPay Client Agent Adapter
+ * Equips autonomous AI agents with automatic x402 challenge negotiation, spend policies, and payment signing.
+ */
+import { type Hex, type Address } from 'viem';
+import { JsonRpcRequest } from '../types/mcp.js';
+import { PaymentProof } from '../types/x402.js';
+import { GatewayResponse } from '../gateway/toolpay-gateway.js';
+export interface AgentSpendPolicy {
+    /** Maximum price willing to pay for a single tool call in USD (e.g. "0.05") */
+    maxPricePerCallUsd?: string;
+    /** Maximum total spend across the agent's lifetime or run */
+    maxTotalBudgetUsd?: string;
+    /** Auto-approve payments below max price without human intervention */
+    autoApprove?: boolean;
+}
+/**
+ * Builds the exact ABI-encoded transaction calldata to pay the ToolPayRouter smart contract on Base.
+ */
+export declare function buildRouterPaymentCalldata(params: {
+    developerWallet: Address;
+    tokenAddress: Address;
+    grossAmountMicro: bigint;
+    challengeNonce: string;
+    serverId: string;
+    toolName: string;
+}): `0x${string}`;
+export interface ToolPayClientAgentOptions {
+    privateKey?: Hex;
+    walletAddress?: string;
+    spendPolicy?: AgentSpendPolicy;
+    sessionId?: string;
+}
+export declare class ToolPayClientAgent {
+    readonly walletAddress: string;
+    private privateKey?;
+    private spendPolicy;
+    private totalSpentMicro;
+    private sessionId?;
+    constructor(params: ToolPayClientAgentOptions);
+    /**
+     * Invokes an MCP tool through a ToolPay gateway, automatically handling 402 challenges.
+     */
+    executeToolCall(request: JsonRpcRequest, callerFn: (req: JsonRpcRequest, paymentProof?: PaymentProof) => Promise<GatewayResponse>): Promise<GatewayResponse>;
+    getTotalSpentMicro(): bigint;
+}
+//# sourceMappingURL=client-agent.d.ts.map

package/dist/sdk/client-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-agent.d.ts","sourceRoot":"","sources":["../../src/sdk/client-agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,OAAO,EAAsB,MAAM,MAAM,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAqB,MAAM,kBAAkB,CAAC;AAGnE,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGhE,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,OAAO,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,KAAK,MAAM,EAAE,CAchB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,kBAAkB;IAC7B,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,OAAO,CAAC,UAAU,CAAC,CAAM;IACzB,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,MAAM,EAAE,yBAAyB;IAmB7C;;OAEG;IACU,eAAe,CAC1B,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,eAAe,CAAC,GACvF,OAAO,CAAC,eAAe,CAAC;IAwHpB,kBAAkB,IAAI,MAAM;CAGpC"}

package/dist/sdk/client-agent.js

@@ -0,0 +1,158 @@
+/**
+ * ToolPay Client Agent Adapter
+ * Equips autonomous AI agents with automatic x402 challenge negotiation, spend policies, and payment signing.
+ */
+import { privateKeyToAccount } from 'viem/accounts';
+import { encodeFunctionData } from 'viem';
+import { TOOLPAY_PERMIT_DOMAIN, TOOLPAY_PERMIT_TYPES } from '../settlement/permit-verifier.js';
+import { usdToMicro, normalizeNonceToBytes32 } from '../utils/units.js';
+import { TOOLPAY_ROUTER_ABI } from '../contracts/ToolPayRouter.js';
+/**
+ * Builds the exact ABI-encoded transaction calldata to pay the ToolPayRouter smart contract on Base.
+ */
+export function buildRouterPaymentCalldata(params) {
+    const nonceBytes32 = normalizeNonceToBytes32(params.challengeNonce);
+    return encodeFunctionData({
+        abi: TOOLPAY_ROUTER_ABI,
+        functionName: 'payForTool',
+        args: [
+            params.tokenAddress,
+            params.developerWallet,
+            params.grossAmountMicro,
+            nonceBytes32,
+            params.serverId,
+            params.toolName,
+        ],
+    });
+}
+export class ToolPayClientAgent {
+    walletAddress;
+    privateKey;
+    spendPolicy;
+    totalSpentMicro = 0n;
+    sessionId;
+    constructor(params) {
+        this.privateKey = params.privateKey;
+        this.spendPolicy = {
+            autoApprove: true,
+            maxPricePerCallUsd: '0.10',
+            ...params.spendPolicy,
+        };
+        this.sessionId = params.sessionId;
+        if (this.privateKey) {
+            const account = privateKeyToAccount(this.privateKey);
+            this.walletAddress = account.address;
+        }
+        else if (params.walletAddress) {
+            this.walletAddress = params.walletAddress.toLowerCase();
+        }
+        else {
+            this.walletAddress = '0x0000000000000000000000000000000000000000';
+        }
+    }
+    /**
+     * Invokes an MCP tool through a ToolPay gateway, automatically handling 402 challenges.
+     */
+    async executeToolCall(request, callerFn) {
+        // 1. Initial attempt without payment proof to determine tool pricing terms
+        const firstAttempt = await callerFn(request, undefined);
+        // If call succeeded or errored with non-402, return immediately
+        if (firstAttempt.statusCode !== 402) {
+            return firstAttempt;
+        }
+        // 2. Parse 402 Challenge Data
+        const challengePayload = firstAttempt.body?.error?.data;
+        if (!challengePayload || !challengePayload.challengeNonce) {
+            return firstAttempt; // Malformed 402
+        }
+        const priceUsd = challengePayload.priceUsd;
+        const priceMicro = BigInt(challengePayload.amountMicro);
+        // Warn (not fail) when the gateway settles through a non-official
+        // router. Official hosted traffic uses OFFICIAL_ROUTER_ADDRESS_BASE;
+        // self-hosted forks use their own contract and are outside the hosted
+        // network / fee enforcement (see OPERATOR-LICENSE.md).
+        try {
+            const { isOfficialRouter } = await import('../contracts/router-registry.js');
+            const routerAddr = challengePayload.verifyingContract || challengePayload.recipientWallet;
+            if (routerAddr && !isOfficialRouter(routerAddr, challengePayload.chainId)) {
+                console.warn(`[MCPaid] Gateway router ${routerAddr} is not the official hosted router — ` +
+                    `you are paying a self-hosted gateway outside mcpaid.dev fee/settlement guarantees.`);
+            }
+        }
+        catch { }
+        // 3. Spend Policy Checks
+        if (this.spendPolicy.autoApprove === false) {
+            throw new Error(`Agent Spend Policy Rejected: autoApprove is disabled for paid tool "${challengePayload.toolName}" ($${priceUsd})`);
+        }
+        if (this.spendPolicy.maxPricePerCallUsd) {
+            const maxPriceMicro = usdToMicro(this.spendPolicy.maxPricePerCallUsd);
+            if (priceMicro > maxPriceMicro) {
+                throw new Error(`Agent Spend Policy Rejected: tool price $${priceUsd} exceeds maximum per-call budget $${this.spendPolicy.maxPricePerCallUsd}`);
+            }
+        }
+        if (this.spendPolicy.maxTotalBudgetUsd) {
+            const maxTotalMicro = usdToMicro(this.spendPolicy.maxTotalBudgetUsd);
+            if (this.totalSpentMicro + priceMicro > maxTotalMicro) {
+                throw new Error(`Agent Spend Policy Rejected: cumulative spend with this call would exceed total budget $${this.spendPolicy.maxTotalBudgetUsd}`);
+            }
+        }
+        // 4. Generate and Sign Payment Proof
+        let paymentProof;
+        if (this.sessionId) {
+            // Use Session Wallet
+            paymentProof = {
+                scheme: 'session-wallet',
+                challengeNonce: challengePayload.challengeNonce,
+                signerWallet: this.walletAddress,
+                sessionId: this.sessionId,
+            };
+        }
+        else if (this.privateKey) {
+            // Sign EIP-712 Micro-Voucher
+            const account = privateKeyToAccount(this.privateKey);
+            const deadline = challengePayload.expiresAt;
+            const message = {
+                serverId: challengePayload.serverId,
+                toolName: challengePayload.toolName,
+                challengeNonce: challengePayload.challengeNonce,
+                amountMicro: priceMicro,
+                recipient: challengePayload.recipientWallet,
+                deadline: BigInt(deadline),
+            };
+            const domain = {
+                ...TOOLPAY_PERMIT_DOMAIN,
+                chainId: challengePayload.chainId || 8453,
+                verifyingContract: challengePayload.verifyingContract || TOOLPAY_PERMIT_DOMAIN.verifyingContract,
+            };
+            const signature = await account.signTypedData({
+                domain,
+                types: TOOLPAY_PERMIT_TYPES,
+                primaryType: 'ToolPayment',
+                message,
+            });
+            paymentProof = {
+                scheme: 'eip712-permit',
+                challengeNonce: challengePayload.challengeNonce,
+                signerWallet: this.walletAddress,
+                signature,
+                deadline,
+                maxAmountMicro: priceMicro,
+            };
+        }
+        else {
+            throw new Error(`Payment Required: Tool "${challengePayload.toolName}" costs ${challengePayload.priceUsd} ${challengePayload.currency}. ` +
+                `No signing key or session wallet is configured for this agent. ` +
+                `To authorize payments, set AGENT_PRIVATE_KEY=0x... in your project .env file or pass --key <private-key> to the mcpaid bridge.`);
+        }
+        // 5. Replay request with Payment Proof
+        const secondAttempt = await callerFn(request, paymentProof);
+        if (secondAttempt.statusCode === 200) {
+            this.totalSpentMicro += priceMicro;
+        }
+        return secondAttempt;
+    }
+    getTotalSpentMicro() {
+        return this.totalSpentMicro;
+    }
+}
+//# sourceMappingURL=client-agent.js.map

package/dist/sdk/client-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-agent.js","sourceRoot":"","sources":["../../src/sdk/client-agent.ts"],"names":[],"mappings":"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"}