@paidfor/mcp 0.2.1 → 0.3.1

package/README.md

@@ -4,14 +4,17 @@ MCP server for [paidfor.dev](https://paidfor.dev), the x402 seller failure index
 
 **No account, no key.** Everything that reads the index or contributes data (the site, the API, the MCP tools, the client, telemetry and the changes feed) needs no account and no key, now and later. An email address is asked for only to deliver alerts or to join a waitlist, as a confirmation link, never a profile.
 
-Two tools:
+Three read tools on every transport, plus two paying tools on stdio only when a wallet is configured:
 
 - `check_x402_seller({ url })`: verdict (`avoid`, `caution`, `ok`, `unknown`) and one sentence for an x402 resource URL or seller domain, with the seller's paid-call count, failure rate and 95% interval, the resource's listed price, modal quote and max overcharge ratio when known, and links to the seller page and raw evidence.
 - `list_reliable_sellers({ category?, limit? })`: zero-failure sellers with at least 30 paid calls.
+- `recent_changes({ host?, since? })`: what changed, newest first (verdicts, new failures, moved quotes, pay-to addresses, replies, the operator series maturing or disagreeing); called when the user asks what changed or before relying on a verdict older than a day. Reads `GET https://paidfor.dev/v1/changes`.
+- `pay_x402({ url, method?, headers?, body?, intent_id?, max_usd? })` (stdio, wallet configured): pays through [`@paidfor/x402-safe-fetch`](https://www.npmjs.com/package/@paidfor/x402-safe-fetch) with your own wallet. See "Let your agent pay, safely" below.
+- `wallet_status()` (stdio, wallet configured): the paying address, its USDC balance on Base, the limits and today's spend. Never the key.
 
 On initialize the server sends `instructions` telling the client to call `check_x402_seller` before any x402 payment or retry, unprompted, and how to act on each verdict; the text is `INSTRUCTIONS` in `src/server.ts`, shared by every transport. Per-client setup: https://paidfor.dev/install.
 
-Both read the public JSON API (`GET https://paidfor.dev/v1/check`, `GET https://paidfor.dev/v1/sellers`). No keys, no rate limit for now.
+The read tools use the public JSON API (`GET https://paidfor.dev/v1/check`, `/v1/sellers`, `/v1/changes`). No keys, no rate limit for now.
 
 ## Hosted (Streamable HTTP)
 
@@ -35,6 +38,43 @@ Both read the public JSON API (`GET https://paidfor.dev/v1/check`, `GET https://
 }
 ```
 
+## Let your agent pay, safely (stdio only)
+
+`pay_x402` pays an x402 seller with **your own wallet**, through `@paidfor/x402-safe-fetch` 0.2.0: it checks the seller on paidfor first and refuses `avoid` sellers, refuses quotes over 1.1x the listed price, caps the amount per call and per day, never pays twice for the same `intent_id` (a retry returns the stored result), keeps receipts in `~/.paidfor/receipts/`, and reports the outcome with its proof of payment (payer, nonce, pay-to, tx hash) to `https://paidfor.dev/v1/telemetry`, where it is checked on Base. It returns the status, the body (truncated at 64 KB) and a receipt with the amount, pay-to, tx hash and basescan link, the seller verdict at purchase, the validator results and the `verification_url` that shows whether the index verified it.
+
+**Use a dedicated wallet holding a few dollars, never your main wallet.** There is no custody and no account: the key stays on your machine, is read only to sign, and is never logged, returned by a tool or sent anywhere.
+
+```bash
+npx -y @paidfor/mcp wallet new
+# prints the address and: fund this with a few USDC on Base; x402 payments on Base are gasless for the buyer, no ETH needed
+```
+
+That writes `~/.paidfor/wallet.key` with mode 600 (it never overwrites an existing key). Send a few USDC on Base to the address, then point the server at the key:
+
+```json
+{
+  "mcpServers": {
+    "paidfor": {
+      "command": "npx",
+      "args": ["-y", "@paidfor/mcp"],
+      "env": { "PAIDFOR_WALLET_KEY_FILE": "/Users/you/.paidfor/wallet.key" }
+    }
+  }
+}
+```
+
+Verify by asking the agent to call `wallet_status`.
+
+| env | default | |
+|---|---|---|
+| `PAIDFOR_WALLET_KEY_FILE` | | path to the key file; refused if group- or world-readable (`chmod 600`) |
+| `PAIDFOR_WALLET_KEY` | | the key inline; discouraged, use the file |
+| `PAIDFOR_MAX_PER_CALL_USD` | `0.50` | most one call may pay; `max_usd` can lower it, never raise it |
+| `PAIDFOR_DAILY_CAP_USD` | `5` | most all calls may pay per UTC day (tracked in `~/.paidfor/spend.json`) |
+| `BASE_RPC_URL` | `https://mainnet.base.org` | used only by `wallet_status` for the balance |
+
+Without a key (or with a misconfigured one, reported on stderr) the stdio server is the read-only server. The hosted server at `mcp.paidfor.dev` and the site's `/mcp` route never register `pay_x402` or `wallet_status`, by design: they never hold a key.
+
 ## Run the HTTP service yourself
 
 This folder is a standalone Node project (own `package.json` and `pnpm-lock.yaml`):

package/dist/http.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/http.js

@@ -0,0 +1,49 @@
+/**
+ * Standalone Streamable HTTP service (Railway / Fly / any Node host). Stateless: one
+ * transport per request. GET /health for the platform health check.
+ */
+import { createServer as createHttpServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer, TOOL_NAMES, VERSION } from "./server.js";
+const port = Number(process.env.PORT ?? 3402);
+const counts = new Map();
+const bump = (k) => counts.set(k, (counts.get(k) ?? 0) + 1);
+const CORS = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS", "Access-Control-Allow-Headers": "*" };
+createHttpServer(async (req, res) => {
+    const path = (req.url ?? "/").split("?")[0];
+    if (req.method === "OPTIONS") {
+        res.writeHead(204, CORS);
+        res.end();
+        return;
+    }
+    if (path === "/health") {
+        res.writeHead(200, { "Content-Type": "text/plain", ...CORS });
+        res.end("ok");
+        return;
+    }
+    if (path === "/usage") {
+        res.writeHead(200, { "Content-Type": "application/json", ...CORS });
+        res.end(JSON.stringify(Object.fromEntries(counts)));
+        return;
+    }
+    if (path === "/" || path === "/mcp") {
+        if (req.method === "GET" && !(req.headers.accept ?? "").includes("text/event-stream")) {
+            res.writeHead(200, { "Content-Type": "application/json", ...CORS });
+            res.end(JSON.stringify({ name: "paidfor", version: VERSION, transport: "streamable-http", tools: TOOL_NAMES, usage: "POST JSON-RPC 2.0 to this URL" }));
+            return;
+        }
+        bump("request");
+        for (const [k, v] of Object.entries(CORS))
+            res.setHeader(k, v);
+        const server = createServer({ onToolCall: bump });
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => { void transport.close(); void server.close(); });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+        return;
+    }
+    res.writeHead(404, CORS);
+    res.end();
+}).listen(port, () => {
+    console.log(`paidfor MCP (streamable http) listening on :${port}, reading ${process.env.PAIDFOR_URL ?? "https://paidfor.dev"}`);
+});

package/dist/index.js

@@ -10,7 +10,7 @@
  */
 import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createServer, DEFAULT_BASE, TOOL_NAMES, VERSION } from "./server.js";
+import { CLIENT_HEADER, createServer, DEFAULT_BASE, TOOL_NAMES, VERSION } from "./server.js";
 const base = (process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
 const port = Number(process.env.PORT ?? 3000);
 const host = process.env.HOST ?? "0.0.0.0";
@@ -21,7 +21,7 @@ const noteGeneratedAt = (g) => {
     if (g)
         dataGeneratedAt = g;
 };
-fetch(`${base}/v1/summary`, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}` } })
+fetch(`${base}/v1/summary`, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}`, "X-Paidfor-Client": CLIENT_HEADER } })
     .then((r) => (r.ok ? r.json() : null))
     .then((j) => noteGeneratedAt(j?.generated_at))
     .catch(() => undefined);

package/dist/pay.d.ts

@@ -0,0 +1,49 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Receipt, type SafeNetwork } from "@paidfor/x402-safe-fetch";
+import { type Limits, type LoadedWallet } from "./wallet.js";
+export declare const PAY_TOOL_NAMES: readonly ["pay_x402", "wallet_status"];
+export declare const BODY_LIMIT_BYTES: number;
+export declare const PAY_INSTRUCTIONS: string;
+/** The stdio server's instructions with a wallet configured: the pay paragraph goes in before the no-account promise, which stays last. */
+export declare const INSTRUCTIONS_WITH_PAY: string;
+export declare const PAY_DESCRIPTION: string;
+export declare const WALLET_STATUS_DESCRIPTION: string;
+export type PayOptions = {
+    wallet: LoadedWallet;
+    limits: Limits;
+    /** Site origin; telemetry goes to `${baseUrl}/v1/telemetry`. */
+    baseUrl: string;
+    /** Default ~/.paidfor (receipts in ./receipts, today's spend in ./spend.json). */
+    dir?: string;
+    /** Tests only: a local network and fetch. Default Base mainnet and globalThis.fetch. */
+    network?: SafeNetwork;
+    fetch?: typeof globalThis.fetch;
+    /** wallet_status balance; default reads USDC.balanceOf on Base over BASE_RPC_URL or https://mainnet.base.org. */
+    balanceOf?: (address: `0x${string}`) => Promise<bigint>;
+};
+/** The receipt as pay_x402 reports it: what was paid, to whom, the proof, and how to check it. */
+export declare function receiptSummary(r: Receipt): {
+    outcome: import("@paidfor/x402-safe-fetch").Outcome;
+    paid: boolean;
+    replayed: boolean;
+    intent_id: string;
+    amount_usdc: string;
+    pay_to: string | null;
+    tx_hash: string | null;
+    basescan_url: string | null;
+    seller: {
+        host: string | null;
+        verdict_at_purchase: import("@paidfor/x402-safe-fetch").Verdict;
+        verdict_text: string | null;
+        seller_url: string | null;
+    };
+    validators: Partial<Record<import("@paidfor/x402-safe-fetch").ValidatorName, import("@paidfor/x402-safe-fetch").ValidatorResult>>;
+    validator_failures: import("@paidfor/x402-safe-fetch").ValidatorName[];
+    reported_outcome: import("@paidfor/x402-safe-fetch").TelemetryOutcome | null;
+    verification_url: string | null;
+};
+export declare function truncateBody(body: string): {
+    body: string;
+    note: string | null;
+};
+export declare function registerPayTools(server: McpServer, o: PayOptions): Promise<void>;

package/dist/pay.js

@@ -0,0 +1,166 @@
+/**
+ * pay_x402 and wallet_status: the stdio-only tools that buy through @paidfor/x402-safe-fetch with the
+ * user's own wallet and report the verified outcome to the index. Only stdio.ts imports this module;
+ * the hosted service (index.ts) and the site's /mcp route never do, because they never hold a key.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { PaymentRefusedError, SafeFetchError, safeFetch } from "@paidfor/x402-safe-fetch";
+import { createPublicClient, erc20Abi, http } from "viem";
+import { base as baseChain } from "viem/chains";
+import { z } from "zod";
+import { INSTRUCTIONS, NO_ACCOUNT_PROMISE } from "./server.js";
+import { SpendLedger, fromMicro, paidforDir, toMicro } from "./wallet.js";
+export const PAY_TOOL_NAMES = ["pay_x402", "wallet_status"];
+export const BODY_LIMIT_BYTES = 64 * 1024;
+const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** The client's smallest positive cap: with the daily budget spent, any quote is refused before signing. */
+const MIN_CAP_USD = 0.000001;
+export const PAY_INSTRUCTIONS = "If pay_x402 is available, use it for every x402 purchase instead of any other way of paying; it checks the seller first, refuses avoid sellers, caps the amount, " +
+    "never pays twice for the same intent, and reports the verified outcome to the index. Reuse intent_id when retrying the same purchase. " +
+    "Tell the user the amount and the seller verdict before the first purchase from a new seller. " +
+    "pay_x402 signs with the user's own wallet on this machine; the key never leaves it.";
+/** The stdio server's instructions with a wallet configured: the pay paragraph goes in before the no-account promise, which stays last. */
+export const INSTRUCTIONS_WITH_PAY = INSTRUCTIONS.replace(`\n${NO_ACCOUNT_PROMISE}`, `\n${PAY_INSTRUCTIONS}\n${NO_ACCOUNT_PROMISE}`);
+export const PAY_DESCRIPTION = "Call this to pay for any x402 request (an HTTP 402 asking for USDC on Base) instead of paying any other way. " +
+    "It checks the seller on paidfor first, refuses avoid sellers and quotes over 1.1x the listed price, caps the amount per call and per day, " +
+    "never pays twice for the same intent_id (a retry returns the stored result), and reports the verified outcome to the index. " +
+    "Returns the response status and body (64 KB max) and a receipt: amount, pay-to, tx hash with a basescan link, seller verdict, validator results and verification_url. " +
+    "On refusal it returns the reason and the seller page and pays nothing.";
+export const WALLET_STATUS_DESCRIPTION = "Call this when the user asks which wallet pays, how much USDC it holds, or how much of today's cap is left, and before a first purchase. " +
+    "Returns the address, the USDC balance on Base, the per-call and daily limits and today's spend. Never returns the key.";
+const text = (s, isError = false) => ({ content: [{ type: "text", text: s }], ...(isError ? { isError: true } : {}) });
+const json = (o) => JSON.stringify(o, null, 2);
+/** The receipt as pay_x402 reports it: what was paid, to whom, the proof, and how to check it. */
+export function receiptSummary(r) {
+    const paid = r.replayed ? r.original ?? r : r;
+    const tx = paid.tx_hash;
+    return {
+        outcome: r.outcome,
+        paid: r.paid,
+        replayed: r.replayed,
+        intent_id: r.intent_id,
+        amount_usdc: paid.amount_usdc,
+        pay_to: paid.quote?.pay_to ?? null,
+        tx_hash: tx,
+        basescan_url: tx ? `https://basescan.org/tx/${tx}` : null,
+        seller: { host: r.seller.host, verdict_at_purchase: r.seller.verdict, verdict_text: r.seller.verdict_text, seller_url: r.seller.seller_url },
+        validators: r.validators,
+        validator_failures: r.validator_failures,
+        reported_outcome: paid.reported_outcome,
+        verification_url: paid.verification_url,
+    };
+}
+export function truncateBody(body) {
+    const buf = Buffer.from(body, "utf8");
+    if (buf.byteLength <= BODY_LIMIT_BYTES)
+        return { body, note: null };
+    // Cut on a character boundary at or under the limit.
+    const cut = new TextDecoder("utf-8", { fatal: false }).decode(buf.subarray(0, BODY_LIMIT_BYTES)).replace(/�$/, "");
+    return { body: cut, note: `body truncated at 64 KB of ${buf.byteLength} bytes` };
+}
+function defaultBalanceOf(address) {
+    const client = createPublicClient({ chain: baseChain, transport: http(process.env.BASE_RPC_URL || "https://mainnet.base.org") });
+    return client.readContract({ address: USDC_BASE, abi: erc20Abi, functionName: "balanceOf", args: [address] });
+}
+export async function registerPayTools(server, o) {
+    const dir = o.dir ?? paidforDir();
+    const receiptsDir = join(dir, "receipts");
+    await mkdir(receiptsDir, { recursive: true, mode: 0o700 });
+    const ledger = new SpendLedger(join(dir, "spend.json"));
+    const base = o.baseUrl.replace(/\/$/, "");
+    const address = o.wallet.account.address;
+    const logger = { warn: (m) => void process.stderr.write(`${m}\n`) };
+    server.registerTool("pay_x402", {
+        title: "Pay an x402 seller safely",
+        description: PAY_DESCRIPTION,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        inputSchema: {
+            url: z.string().url().describe("The x402 resource URL"),
+            method: z.string().min(1).max(10).optional().describe("HTTP method, default GET"),
+            headers: z.record(z.string(), z.string()).optional().describe("Request headers"),
+            body: z.string().optional().describe("Request body, as text"),
+            intent_id: z.string().min(1).max(200).optional().describe("Reuse the same id when retrying the same purchase; a retry returns the stored result without paying again"),
+            max_usd: z.number().positive().optional().describe("Most to pay for this call in USD; capped by PAIDFOR_MAX_PER_CALL_USD"),
+        },
+    }, async ({ url, method, headers, body, intent_id, max_usd }) => {
+        const spent = await ledger.spentMicro();
+        const leftMicro = toMicro(o.limits.dailyCapUsd) - spent;
+        const perCall = Math.min(max_usd ?? o.limits.maxPerCallUsd, o.limits.maxPerCallUsd);
+        const dailyBinds = leftMicro / 1e6 < perCall;
+        const cap = Math.max(Math.min(perCall, leftMicro / 1e6), MIN_CAP_USD);
+        const limits = {
+            max_per_call_usd: o.limits.maxPerCallUsd,
+            this_call_cap_usd: Number(cap.toFixed(6)),
+            daily_cap_usd: o.limits.dailyCapUsd,
+            spent_today_usdc: fromMicro(spent),
+            ...(max_usd !== undefined && max_usd > o.limits.maxPerCallUsd ? { note: `max_usd ${max_usd} is above PAIDFOR_MAX_PER_CALL_USD; capped at ${o.limits.maxPerCallUsd}` } : {}),
+        };
+        const sf = safeFetch(o.wallet.account, {
+            maxPerCallUsd: cap,
+            maxOverListedRatio: 1.1,
+            refuseVerdicts: ["avoid"],
+            indexUrl: `${base}/v1`,
+            telemetry: "verified",
+            receiptsDir,
+            logger,
+            ...(o.network ? { network: o.network } : {}),
+            ...(o.fetch ? { fetch: o.fetch } : {}),
+        });
+        try {
+            const res = await sf(url, { method: method ?? "GET", headers, body }, { intentId: intent_id });
+            const r = res.receipt;
+            if (r.paid && !r.replayed)
+                await ledger.add(toMicro(r.amount_usdc));
+            const { body: out, note } = truncateBody(await res.text());
+            const head = r.replayed
+                ? `Replayed the stored result for intent ${r.intent_id}; nothing was paid again.`
+                : r.paid
+                    ? `Paid ${r.amount_usdc} USDC to ${r.quote?.pay_to}; the seller answered HTTP ${res.status} (${r.outcome}).`
+                    : `No payment was needed; the server answered HTTP ${res.status}.`;
+            return text(`${head}\n\n${json({ status: res.status, receipt: receiptSummary(r), limits, ...(note ? { body_note: note } : {}) })}\n\n--- response body ---\n${out}`);
+        }
+        catch (e) {
+            if (e instanceof PaymentRefusedError) {
+                const why = e.code === "refused_max_per_call" && dailyBinds
+                    ? `refused: today's cap of ${o.limits.dailyCapUsd} USD (PAIDFOR_DAILY_CAP_USD) leaves ${fromMicro(Math.max(leftMicro, 0))} USDC. ${e.message}`
+                    : e.code === "refused_max_per_call"
+                        ? `refused: the quote is above this call's cap of ${cap} USD (max_usd, capped by PAIDFOR_MAX_PER_CALL_USD ${o.limits.maxPerCallUsd}). ${e.message}`
+                        : `refused: ${e.message}`;
+                return text(`${why}\nNothing was paid.\n\n${json({ refused: e.code, paid: false, seller_url: e.sellerUrl ?? e.receipt?.seller.seller_url ?? null, intent_id: e.receipt?.intent_id ?? intent_id ?? null, limits })}`);
+            }
+            if (e instanceof SafeFetchError) {
+                return text(`${e.code}: ${e.message}\n\n${json({ error: e.code, paid: e.receipt?.paid ?? false, receipt: e.receipt ? receiptSummary(e.receipt) : null, limits })}`, true);
+            }
+            return text(`error: ${e instanceof Error ? e.message : String(e)}`, true);
+        }
+    });
+    server.registerTool("wallet_status", {
+        title: "Show the paying wallet",
+        description: WALLET_STATUS_DESCRIPTION,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: {},
+    }, async () => {
+        const spent = await ledger.spentMicro();
+        let usdc = null;
+        let balance_error = null;
+        try {
+            usdc = fromMicro(Number(await (o.balanceOf ?? defaultBalanceOf)(address)));
+        }
+        catch (e) {
+            balance_error = e instanceof Error ? e.message.split("\n")[0] : String(e);
+        }
+        const s = {
+            address,
+            network: "eip155:8453",
+            usdc_balance: usdc,
+            ...(balance_error ? { balance_error } : {}),
+            basescan_url: `https://basescan.org/address/${address}`,
+            key_source: o.wallet.source === "file" ? "PAIDFOR_WALLET_KEY_FILE" : "PAIDFOR_WALLET_KEY (discouraged; prefer a key file)",
+            max_per_call_usd: o.limits.maxPerCallUsd,
+            daily_cap_usd: o.limits.dailyCapUsd,
+            spent_today_usdc: fromMicro(spent),
+        };
+        return text(`${usdc === null ? "Balance unavailable" : `${usdc} USDC on Base`} at ${address}.\n\n${json(s)}`);
+    });
+}

package/dist/rules.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The one copy of the rules an agent follows: when to check, what each verdict means, and never paying twice.
+ * The server instructions and the tool descriptions (server.ts) and the skill at paidfor.dev/skill.md (lib/skill.ts on
+ * the site) are all generated from these constants, so the three copies cannot drift.
+ *
+ * Changing any text here changes the skill: bump RULES_REVISION (the skill's `skill-revision`) and update RULES_SHA;
+ * lib/skill.test.ts fails until both move together.
+ */
+export declare const RULES_REVISION = "2026-10-29";
+/** When to call check_x402_seller (GET /v1/check), in order. */
+export declare const CHECK_TRIGGERS: readonly ["before any x402 payment", "before retrying a request that answered HTTP 402", "whenever the user is about to buy an API call with USDC on Base or names an API they intend to pay per call"];
+/** When to call list_reliable_sellers (GET /v1/sellers?zero_failures=1). */
+export declare const CHOOSE_TRIGGER = "when choosing among sellers for a task";
+/** When to call recent_changes (GET /v1/changes). */
+export declare const CHANGES_TRIGGER = "when the user asks what changed, or before relying on a verdict older than a day";
+/** What to do for each verdict. */
+export declare const VERDICT_RULES: {
+    readonly avoid: "do not pay an \"avoid\" seller and say why with the evidence link";
+    readonly caution: "before paying a \"caution\" seller tell the user the failure rate";
+    readonly ok: "\"ok\" needs no comment";
+    readonly unknown: "\"unknown\" means no data, say so and proceed only on the user's say-so";
+};
+export declare const NEVER_PAY_TWICE = "Never pay the same seller twice for one task because of a timeout or error without checking first.";
+export declare const SENDS_ONLY_URL = "These tools read a public index, need no key, and send nothing but the URL being checked.";
+/** sha256 of the JSON of every constant above (lib/skill.test.ts recomputes it). */
+export declare const RULES_SHA = "7258b901f6577a02dfe997416d3de61e122f5da21476eb686dd1c1a9379bffc6";
+/** "a, b, and c" */
+export declare function listAnd(xs: readonly string[]): string;
+/** "a, b, or c" */
+export declare function listOr(xs: readonly string[]): string;
+export declare const cap: (s: string) => string;
+/** The verdict rules as one sentence (server instructions, skill). */
+export declare const VERDICT_SENTENCE: string;

package/dist/rules.js

@@ -0,0 +1,41 @@
+/**
+ * The one copy of the rules an agent follows: when to check, what each verdict means, and never paying twice.
+ * The server instructions and the tool descriptions (server.ts) and the skill at paidfor.dev/skill.md (lib/skill.ts on
+ * the site) are all generated from these constants, so the three copies cannot drift.
+ *
+ * Changing any text here changes the skill: bump RULES_REVISION (the skill's `skill-revision`) and update RULES_SHA;
+ * lib/skill.test.ts fails until both move together.
+ */
+export const RULES_REVISION = "2026-10-29";
+/** When to call check_x402_seller (GET /v1/check), in order. */
+export const CHECK_TRIGGERS = [
+    "before any x402 payment",
+    "before retrying a request that answered HTTP 402",
+    "whenever the user is about to buy an API call with USDC on Base or names an API they intend to pay per call",
+];
+/** When to call list_reliable_sellers (GET /v1/sellers?zero_failures=1). */
+export const CHOOSE_TRIGGER = "when choosing among sellers for a task";
+/** When to call recent_changes (GET /v1/changes). */
+export const CHANGES_TRIGGER = "when the user asks what changed, or before relying on a verdict older than a day";
+/** What to do for each verdict. */
+export const VERDICT_RULES = {
+    avoid: 'do not pay an "avoid" seller and say why with the evidence link',
+    caution: 'before paying a "caution" seller tell the user the failure rate',
+    ok: '"ok" needs no comment',
+    unknown: '"unknown" means no data, say so and proceed only on the user\'s say-so',
+};
+export const NEVER_PAY_TWICE = "Never pay the same seller twice for one task because of a timeout or error without checking first.";
+export const SENDS_ONLY_URL = "These tools read a public index, need no key, and send nothing but the URL being checked.";
+/** sha256 of the JSON of every constant above (lib/skill.test.ts recomputes it). */
+export const RULES_SHA = "7258b901f6577a02dfe997416d3de61e122f5da21476eb686dd1c1a9379bffc6";
+/** "a, b, and c" */
+export function listAnd(xs) {
+    return xs.length < 2 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")}, and ${xs.at(-1)}`;
+}
+/** "a, b, or c" */
+export function listOr(xs) {
+    return xs.length < 2 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")}, or ${xs.at(-1)}`;
+}
+export const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** The verdict rules as one sentence (server instructions, skill). */
+export const VERDICT_SENTENCE = `Follow the verdict: ${[VERDICT_RULES.avoid, VERDICT_RULES.caution, VERDICT_RULES.ok, VERDICT_RULES.unknown].join("; ")}.`;

package/dist/server.d.ts

@@ -1,21 +1,27 @@
 /**
  * The paidfor MCP server. One factory, three transports: stdio (npx @paidfor/mcp),
  * the hosted Streamable HTTP service (index.ts) and the Next.js route at /mcp on the site.
- * Both tools are thin readers of the public JSON API; the verdict logic lives on the site.
+ * The read tools are thin readers of the public JSON API; the verdict logic lives on the site.
+ * The paying tools (pay.ts) are added by stdio.ts alone, and only when a wallet is configured.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const VERSION = "0.2.1";
+export * from "./rules.js";
+export declare const VERSION = "0.3.1";
+/** Sent on every request to the index so usage can be counted by channel (never anything else). */
+export declare const CLIENT_HEADER = "mcp/0.3.1";
 export declare const DEFAULT_BASE = "https://paidfor.dev";
-export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers"];
+export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
 /**
  * The no-account promise, word for word wherever it appears: the server instructions (last line),
  * this package's README, /methodology, /install.md and /privacy on the site.
  */
 export declare const NO_ACCOUNT_PROMISE: string;
-/** Sent on initialize by every transport (stdio, the hosted service, the site's /mcp route), so clients call the tools unprompted. */
+/** Sent on initialize by every transport (stdio, the hosted service, the site's /mcp route), so clients call the tools unprompted.
+ * Generated from rules.ts, like the tool descriptions below and the skill at paidfor.dev/skill.md. */
 export declare const INSTRUCTIONS: string;
 export declare const CHECK_DESCRIPTION: string;
 export declare const LIST_DESCRIPTION: string;
+export declare const CHANGES_DESCRIPTION: string;
 export type ServerOptions = {
     /** Site origin to read from. Defaults to PAIDFOR_API_BASE (or the older PAIDFOR_URL) or https://paidfor.dev. */
     baseUrl?: string;
@@ -23,5 +29,7 @@ export type ServerOptions = {
     onToolCall?: (tool: string) => void;
     /** Called with the export's generated_at from every successful response (the hosted service shows it on /health). */
     onResponse?: (generated_at: string) => void;
+    /** Replaces INSTRUCTIONS; stdio.ts passes INSTRUCTIONS_WITH_PAY when it registers pay_x402. */
+    instructions?: string;
 };
 export declare function createServer(opts?: ServerOptions): McpServer;

package/dist/server.js

@@ -1,13 +1,18 @@
 /**
  * The paidfor MCP server. One factory, three transports: stdio (npx @paidfor/mcp),
  * the hosted Streamable HTTP service (index.ts) and the Next.js route at /mcp on the site.
- * Both tools are thin readers of the public JSON API; the verdict logic lives on the site.
+ * The read tools are thin readers of the public JSON API; the verdict logic lives on the site.
+ * The paying tools (pay.ts) are added by stdio.ts alone, and only when a wallet is configured.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-export const VERSION = "0.2.1";
+import { CHANGES_TRIGGER, CHECK_TRIGGERS, CHOOSE_TRIGGER, NEVER_PAY_TWICE, SENDS_ONLY_URL, VERDICT_SENTENCE, cap, listAnd, listOr } from "./rules.js";
+export * from "./rules.js";
+export const VERSION = "0.3.1";
+/** Sent on every request to the index so usage can be counted by channel (never anything else). */
+export const CLIENT_HEADER = `mcp/${VERSION}`;
 export const DEFAULT_BASE = "https://paidfor.dev";
-export const TOOL_NAMES = ["check_x402_seller", "list_reliable_sellers"];
+export const TOOL_NAMES = ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
 const CATEGORIES = ["inference", "data", "scraping", "compute", "other"];
 /**
  * The no-account promise, word for word wherever it appears: the server instructions (last line),
@@ -15,32 +20,36 @@ const CATEGORIES = ["inference", "data", "scraping", "compute", "other"];
  */
 export const NO_ACCOUNT_PROMISE = "Everything that reads the index or contributes data (the site, the API, the MCP tools, the client, telemetry and the changes feed) needs no account and no key, now and later. " +
     "An email address is asked for only to deliver alerts or to join a waitlist, as a confirmation link, never a profile.";
-/** Sent on initialize by every transport (stdio, the hosted service, the site's /mcp route), so clients call the tools unprompted. */
+/** Sent on initialize by every transport (stdio, the hosted service, the site's /mcp route), so clients call the tools unprompted.
+ * Generated from rules.ts, like the tool descriptions below and the skill at paidfor.dev/skill.md. */
 export const INSTRUCTIONS = "paidfor rates x402 sellers by paying them and verifying delivery. " +
-    "Before any x402 payment, before retrying a request that answered HTTP 402, and whenever the user is about to buy an API call with USDC on Base, " +
-    "call check_x402_seller on the URL or seller domain first, without being asked. " +
-    'Follow the verdict: do not pay an "avoid" seller and say why with the evidence link; before paying a "caution" seller tell the user the failure rate; ' +
-    '"ok" needs no comment; "unknown" means no data, say so and proceed only on the user\'s say-so. ' +
-    "When choosing among sellers for a task, prefer results from list_reliable_sellers. " +
-    "Never pay the same seller twice for one task because of a timeout or error without checking first. " +
-    "These tools read a public index, need no key, and send nothing but the URL being checked.\n" +
+    `${cap(listAnd(CHECK_TRIGGERS))}, call check_x402_seller on the URL or seller domain first, without being asked. ` +
+    `${VERDICT_SENTENCE} ` +
+    `${cap(CHOOSE_TRIGGER)}, prefer results from list_reliable_sellers. ` +
+    `${cap(CHANGES_TRIGGER)}, call recent_changes. ` +
+    `${NEVER_PAY_TWICE} ` +
+    SENDS_ONLY_URL +
+    "\n" +
     NO_ACCOUNT_PROMISE;
-export const CHECK_DESCRIPTION = "Call this before paying any x402 seller, before retrying a request that returned 402, or when the user names an API they intend to pay per call. " +
+export const CHECK_DESCRIPTION = `Call this ${listOr(CHECK_TRIGGERS)}. ` +
     "Returns a verdict (avoid, caution, ok, unknown), one sentence to act on, the seller's paid-call count and failure rate with a 95% interval, " +
     "listed price, modal quote and max overcharge ratio when known, and links to the seller page and raw evidence.";
-export const LIST_DESCRIPTION = "Call this when choosing which x402 seller to use for a task, or when the user asks for a safe or reliable API. " +
+export const LIST_DESCRIPTION = `Call this ${CHOOSE_TRIGGER}, or when the user asks for a safe or reliable API. ` +
     "Returns sellers with zero failures across at least 30 paid calls, most-called first; optional category filter (inference, data, scraping, compute, other).";
-/** Both tools only read the public index; the directories ask for these hints. */
+export const CHANGES_DESCRIPTION = `Call this ${CHANGES_TRIGGER}. ` +
+    "Returns recent changes, newest first: verdict changes, new failures by type, moved quotes, changed pay-to addresses, sellers added or reaching 30 paid calls, published seller replies, " +
+    "the operator-reported series maturing or disagreeing with ours; optional host filter and since (ISO time).";
+/** The read tools only read the public index; the directories ask for these hints. */
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 async function getJson(url) {
-    const res = await fetch(url, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}` } });
+    const res = await fetch(url, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}`, "X-Paidfor-Client": CLIENT_HEADER } });
     if (!res.ok)
         throw new Error(`${url} returned HTTP ${res.status}`);
     return (await res.json());
 }
 export function createServer(opts = {}) {
     const base = (opts.baseUrl ?? process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
-    const server = new McpServer({ name: "paidfor", version: VERSION }, { instructions: INSTRUCTIONS });
+    const server = new McpServer({ name: "paidfor", version: VERSION }, { instructions: opts.instructions ?? INSTRUCTIONS });
     server.registerTool("check_x402_seller", {
         title: "Check an x402 seller before paying",
         description: CHECK_DESCRIPTION,
@@ -87,5 +96,27 @@ export function createServer(opts = {}) {
         const head = `${rows.length} sellers with zero failures across at least 30 paid calls${category ? ` in ${category}` : ""} (index generated ${r.generated_at}).`;
         return { content: [{ type: "text", text: `${head}\n\n${JSON.stringify(rows, null, 2)}` }] };
     });
+    server.registerTool("recent_changes", {
+        title: "Recent changes to x402 sellers",
+        description: CHANGES_DESCRIPTION,
+        annotations: READ_ONLY,
+        inputSchema: {
+            host: z.string().min(1).optional().describe("Only this seller, a bare domain such as api.example.com"),
+            since: z.string().min(1).optional().describe("Only changes after this ISO 8601 time"),
+        },
+    }, async ({ host, since }) => {
+        opts.onToolCall?.("recent_changes");
+        const q = new URLSearchParams();
+        if (host)
+            q.set("host", host);
+        if (since)
+            q.set("since", since);
+        const r = await getJson(`${base}/v1/changes${q.size ? `?${q}` : ""}`);
+        const rows = r.events.slice(0, 100);
+        const head = r.count
+            ? `${r.count} changes${host ? ` for ${host}` : ""}${since ? ` since ${since}` : ""}, newest first${r.count > rows.length ? ` (first ${rows.length} shown)` : ""}.`
+            : `No changes${host ? ` for ${host}` : ""}${since ? ` since ${since}` : ""}. The index is diffed hourly.`;
+        return { content: [{ type: "text", text: `${head}\n\n${JSON.stringify(rows, null, 2)}` }] };
+    });
     return server;
 }

package/dist/stdio.js

@@ -1,5 +1,48 @@
 #!/usr/bin/env node
+/**
+ * `npx @paidfor/mcp`: the stdio server. With PAIDFOR_WALLET_KEY_FILE (or PAIDFOR_WALLET_KEY) set it also
+ * registers pay_x402 and wallet_status; without one it is the same read-only server as the hosted one.
+ * `paidfor-mcp wallet new` writes a fresh key to ~/.paidfor/wallet.key (mode 600) and prints the address.
+ */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createServer } from "./server.js";
-const server = createServer();
-await server.connect(new StdioServerTransport());
+import { DEFAULT_BASE, createServer } from "./server.js";
+import { FUND_SENTENCE, WalletConfigError, loadWallet, newWallet, readLimits } from "./wallet.js";
+const [cmd, sub] = process.argv.slice(2);
+if (cmd === "wallet") {
+    if (sub !== "new") {
+        process.stderr.write("usage: paidfor-mcp wallet new\n");
+        process.exit(2);
+    }
+    try {
+        const { address, file } = await newWallet();
+        process.stdout.write(`${address}\n${FUND_SENTENCE}\n`);
+        process.stderr.write(`key written to ${file} (mode 600); set PAIDFOR_WALLET_KEY_FILE=${file} in your MCP client config\n`);
+        process.exit(0);
+    }
+    catch (e) {
+        process.stderr.write(`paidfor-mcp: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
+    }
+}
+const baseUrl = (process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
+let pay = null;
+let limits = null;
+try {
+    pay = await loadWallet();
+    if (pay)
+        limits = readLimits();
+}
+catch (e) {
+    // A wallet that is misconfigured never pays: start read-only and say why on stderr (never the key).
+    pay = null;
+    process.stderr.write(`paidfor-mcp: pay_x402 disabled: ${e instanceof WalletConfigError ? e.message : "the wallet key could not be loaded"}\n`);
+}
+if (pay && limits) {
+    const { INSTRUCTIONS_WITH_PAY, registerPayTools } = await import("./pay.js");
+    const server = createServer({ baseUrl, instructions: INSTRUCTIONS_WITH_PAY });
+    await registerPayTools(server, { wallet: pay, limits, baseUrl });
+    await server.connect(new StdioServerTransport());
+}
+else {
+    await createServer({ baseUrl }).connect(new StdioServerTransport());
+}

package/dist/wallet.d.ts

@@ -0,0 +1,41 @@
+import { type PrivateKeyAccount } from "viem/accounts";
+export declare const FUND_SENTENCE = "fund this with a few USDC on Base; x402 payments on Base are gasless for the buyer, no ETH needed";
+export declare const DEFAULT_MAX_PER_CALL_USD = 0.5;
+export declare const DEFAULT_DAILY_CAP_USD = 5;
+export type Env = Record<string, string | undefined>;
+/** ~/.paidfor, resolved from HOME at call time. */
+export declare const paidforDir: (home?: string) => string;
+export declare class WalletConfigError extends Error {
+    name: string;
+}
+export type LoadedWallet = {
+    account: PrivateKeyAccount;
+    source: "file" | "env";
+};
+/**
+ * The configured wallet, or null when neither PAIDFOR_WALLET_KEY_FILE nor PAIDFOR_WALLET_KEY is set.
+ * A key file readable by group or others is refused. Error messages never include the key.
+ */
+export declare function loadWallet(env?: Env): Promise<LoadedWallet | null>;
+/** `paidfor-mcp wallet new`: a fresh key in ~/.paidfor/wallet.key, mode 600. Never overwrites an existing key. */
+export declare function newWallet(home?: string): Promise<{
+    address: `0x${string}`;
+    file: string;
+}>;
+export type Limits = {
+    maxPerCallUsd: number;
+    dailyCapUsd: number;
+};
+/** PAIDFOR_MAX_PER_CALL_USD (default 0.50) and PAIDFOR_DAILY_CAP_USD (default 5). */
+export declare function readLimits(env?: Env): Limits;
+/** USDC has 6 decimals; the ledger keeps integer micro-USDC so sums never drift. */
+export declare const toMicro: (usd: number | string) => number;
+export declare const fromMicro: (m: number) => string;
+/** What pay_x402 has spent today (UTC), in ~/.paidfor/spend.json. Only sent authorizations count; replays do not. */
+export declare class SpendLedger {
+    readonly file: string;
+    constructor(file: string);
+    static today(now?: Date): string;
+    spentMicro(now?: Date): Promise<number>;
+    add(micro: number, now?: Date): Promise<number>;
+}

package/dist/wallet.js

@@ -0,0 +1,119 @@
+/**
+ * The buyer's own wallet for pay_x402 (stdio only). No custody and no account: the key is read from a
+ * file the user controls (or, discouraged, an env var), used to sign locally, and never logged, returned
+ * by a tool or sent anywhere. Spending limits and today's running total live next to it in ~/.paidfor.
+ */
+import { mkdir, open, readFile, stat, writeFile, rename } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+export const FUND_SENTENCE = "fund this with a few USDC on Base; x402 payments on Base are gasless for the buyer, no ETH needed";
+export const DEFAULT_MAX_PER_CALL_USD = 0.5;
+export const DEFAULT_DAILY_CAP_USD = 5;
+/** ~/.paidfor, resolved from HOME at call time. */
+export const paidforDir = (home = homedir()) => join(home, ".paidfor");
+export class WalletConfigError extends Error {
+    name = "WalletConfigError";
+}
+const KEY_RE = /^(0x)?[0-9a-fA-F]{64}$/;
+function parseKey(raw, where) {
+    const k = raw.trim();
+    if (!KEY_RE.test(k))
+        throw new WalletConfigError(`${where} does not hold a 32-byte hex private key`);
+    return (k.startsWith("0x") ? k : `0x${k}`);
+}
+/**
+ * The configured wallet, or null when neither PAIDFOR_WALLET_KEY_FILE nor PAIDFOR_WALLET_KEY is set.
+ * A key file readable by group or others is refused. Error messages never include the key.
+ */
+export async function loadWallet(env = process.env) {
+    const file = env.PAIDFOR_WALLET_KEY_FILE?.trim();
+    if (file) {
+        let st;
+        try {
+            st = await stat(file);
+        }
+        catch {
+            throw new WalletConfigError(`PAIDFOR_WALLET_KEY_FILE ${file} cannot be read`);
+        }
+        if (!st.isFile())
+            throw new WalletConfigError(`PAIDFOR_WALLET_KEY_FILE ${file} is not a file`);
+        if (process.platform !== "win32" && (st.mode & 0o077) !== 0) {
+            throw new WalletConfigError(`refused: ${file} is readable by group or others (mode ${(st.mode & 0o777).toString(8)}); run chmod 600 ${file}`);
+        }
+        return { account: privateKeyToAccount(parseKey(await readFile(file, "utf8"), `PAIDFOR_WALLET_KEY_FILE ${file}`)), source: "file" };
+    }
+    const inline = env.PAIDFOR_WALLET_KEY;
+    if (inline && inline.trim())
+        return { account: privateKeyToAccount(parseKey(inline, "PAIDFOR_WALLET_KEY")), source: "env" };
+    return null;
+}
+/** `paidfor-mcp wallet new`: a fresh key in ~/.paidfor/wallet.key, mode 600. Never overwrites an existing key. */
+export async function newWallet(home = homedir()) {
+    const dir = paidforDir(home);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const file = join(dir, "wallet.key");
+    const key = generatePrivateKey();
+    let fh;
+    try {
+        fh = await open(file, "wx", 0o600);
+    }
+    catch (e) {
+        if (e.code === "EEXIST")
+            throw new WalletConfigError(`${file} already exists; not overwriting it`);
+        throw e;
+    }
+    try {
+        await fh.writeFile(key + "\n", "utf8");
+        await fh.chmod(0o600);
+    }
+    finally {
+        await fh.close();
+    }
+    return { address: privateKeyToAccount(key).address, file };
+}
+function positive(env, name, dflt) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return dflt;
+    const n = Number(raw);
+    if (!(Number.isFinite(n) && n > 0))
+        throw new WalletConfigError(`${name} must be a positive number of USD, got ${JSON.stringify(raw)}`);
+    return n;
+}
+/** PAIDFOR_MAX_PER_CALL_USD (default 0.50) and PAIDFOR_DAILY_CAP_USD (default 5). */
+export function readLimits(env = process.env) {
+    return {
+        maxPerCallUsd: positive(env, "PAIDFOR_MAX_PER_CALL_USD", DEFAULT_MAX_PER_CALL_USD),
+        dailyCapUsd: positive(env, "PAIDFOR_DAILY_CAP_USD", DEFAULT_DAILY_CAP_USD),
+    };
+}
+/** USDC has 6 decimals; the ledger keeps integer micro-USDC so sums never drift. */
+export const toMicro = (usd) => Math.round(Number(usd) * 1e6);
+export const fromMicro = (m) => (m / 1e6).toFixed(6);
+/** What pay_x402 has spent today (UTC), in ~/.paidfor/spend.json. Only sent authorizations count; replays do not. */
+export class SpendLedger {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    static today(now = new Date()) {
+        return now.toISOString().slice(0, 10);
+    }
+    async spentMicro(now = new Date()) {
+        try {
+            const j = JSON.parse(await readFile(this.file, "utf8"));
+            return j.day === SpendLedger.today(now) && Number.isFinite(j.spent_micro) ? Number(j.spent_micro) : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async add(micro, now = new Date()) {
+        const total = (await this.spentMicro(now)) + micro;
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        await writeFile(tmp, JSON.stringify({ day: SpendLedger.today(now), spent_micro: total, spent_usdc: fromMicro(total) }) + "\n", { mode: 0o600 });
+        await rename(tmp, this.file);
+        return total;
+    }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "mcpName": "io.github.sarmadahsan/paidfor",
-  "description": "MCP server for the paidfor.dev x402 seller index: check_x402_seller and list_reliable_sellers",
+  "description": "MCP server for the paidfor.dev x402 seller index: check_x402_seller, list_reliable_sellers and recent_changes, plus pay_x402 (stdio, your own wallet)",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -24,6 +24,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
+    "@paidfor/x402-safe-fetch": "0.2.0",
+    "viem": "^2.57.13",
     "zod": "^4.0.0"
   },
   "devDependencies": {