@x402jp/safe-buy 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kato9292929
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @x402jp/safe-buy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+x402（HTTP 402・USDC）の売り手から、買い手エージェントが **1 回の関数呼び出しで安全に買う** ための SDK と MCP サーバー。
+
+- 払う前に止める: Probe の過去記録、402 の入力要件、上限価格、カタログ価格との不一致
+- 払った後に確かめる: 決済ヘッダが無くてもチェーン上で自分の支払いを探し、金額を照合
+- 届かなかったら取り直す: Delivery Receipt 対応の売り手には、同じ支払いで再取得（refetch）して受領証を検証
+
+対応: Base（eip155:8453）と Solana mainnet の公式 USDC、`exact` スキームのみ。Node.js 20 以上。
+
+## インストール
+
+```sh
+npm install @x402jp/safe-buy
+```
+
+## 使い方
+
+```ts
+import { safeBuy } from "@x402jp/safe-buy";
+
+const r = await safeBuy("https://seller.example/api/data", {
+  maxPrice: "$0.01",                       // 必須。既定値なし
+  chain: "base",                           // "base" | "solana" | "any"（既定 any = Base 優先）
+  signer: { evmPrivateKey: process.env.SAFE_BUY_EVM_PRIVATE_KEY },
+  onAttempt: (rec) => ledger.write(rec),   // 送信「前」に呼ばれる。投げると送信しない
+});
+
+if (r.ok) console.log(new TextDecoder().decode(r.body!));
+else console.log(r.outcome, r.stopped_at, r.reason);
+```
+
+鍵は呼び出し側が渡します（`signer` か、組み立て済みの `client: x402Client`）。SDK は鍵を保存もログ出力もしません。`onAttempt` と結果に入るのは支払いを後から探すための買い手側 ID だけです（Solana: 自分の署名、Base: EIP-3009 の nonce と署名の SHA-256。生の署名は出しません）。
+
+### 段階（`stages` にすべて記録）
+
+| # | stage | 内容 | 止まる条件 |
+|---|---|---|---|
+| 1 | probe | `GET {probeUrl}/scores/{host}`（5 秒） | 直近の購入が `not_delivered` / `overcharged`、`buyable_without_input === false` で `input` なし。404・タイムアウト・5xx は続行 |
+| 2 | 402 | 402 を取得し v2（`PAYMENT-REQUIRED`）/ v1（JSON 本文）を解析、`exact` + 公式 USDC を選ぶ | 402 でない、払える accept がない、必須入力があるのに `input` なし |
+| 3 | price | 金額 ≤ `maxPrice`、Probe のカタログ価格と一致 | 上限超え（署名前）、`price_mismatch`（`allowCatalogMismatch` で許可可） |
+| 4 | pay | `@x402/core` / `@x402/evm` / `@x402/svm` で署名、`onAttempt` | 署名失敗、`onAttempt` の例外 |
+| 5 | reconcile | 有償リクエスト送信、決済ヘッダ読み取り、無ければチェーン検索（既定 90 秒）、送金額照合 | — |
+| 6 | refetch | 支払い済みで未着かつ `/.well-known/x402-receipt.json` があれば、元の支払いヘッダ + `X-Payment-Refetch` で再取得 | — |
+| 7 | receipt | 200 に `X-Delivery-Receipt` があれば検証 | — |
+| 8 | report | `report: true` のときだけ、匿名の結果を `{probeUrl}/reports` に POST | 失敗しても購入には影響しない |
+
+`outcome`: `delivered` / `delivered_unsettled`（届いたが支払いが見つからない）/ `not_delivered` / `overcharged`（提示額より多く引かれた）/ `amount_mismatch` / `rejected`（未払いで拒否）/ `failed` / `refused`（払う前に止めた）。`ok` は `delivered` と `delivered_unsettled` のとき true。
+
+報告（stage 8）に入るのは host、URL（クエリなし）、network、金額、結果、HTTP ステータス、レイテンシ、各種フラグだけ。支払者アドレス・tx・買い手側 ID・本文は送りません。
+
+### その他の関数
+
+```ts
+import { checkSeller, verifyReceipt } from "@x402jp/safe-buy";
+
+await checkSeller(url, { maxPrice: 0.01 });           // stage 1〜3 だけ。払わない
+await verifyReceipt({ url, header, body, paymentId }); // well-known を取得して受領証を検証
+```
+
+主なオプション: `probeUrl`（既定 https://probe.x402jp.com）、`input: { method, query, body, headers }`、`rpc: { base, solana }`（既定は環境変数 `BASE_RPC_URL` / `SOLANA_RPC_URL`、無ければ公開 RPC）、`findTimeoutMs`、`report`。
+
+## MCP サーバー
+
+```json
+{
+  "mcpServers": {
+    "x402-safe-buy": {
+      "command": "npx",
+      "args": ["-y", "-p", "@x402jp/safe-buy", "x402-safe-buy-mcp"],
+      "env": { "SAFE_BUY_EVM_PRIVATE_KEY": "0x...", "SAFE_BUY_MAX_PRICE_CAP": "0.05" }
+    }
+  }
+}
+```
+
+ツール:
+
+- `check_seller { url, chain?, maxPrice?, input? }` — 払わずに確認
+- `safe_buy { url, maxPrice, chain?, input?, report? }` — 購入。本文は UTF-8 なら `body_text`（50 KB で切り詰め）、小さなバイナリは `body_base64`
+- `verify_receipt { url, receipt, body_base64, payment_id }`
+
+鍵はサーバーの環境変数（`SAFE_BUY_EVM_PRIVATE_KEY` / `SAFE_BUY_SOLANA_SECRET_KEY`）からのみ読み、ツール引数では受け取りません。`safe_buy` の `maxPrice` は `SAFE_BUY_MAX_PRICE_CAP`（既定 $0.10）を超えると拒否します。
+
+## 試す（実際に支払います）
+
+```sh
+SAFE_BUY_EVM_PRIVATE_KEY=0x... npx tsx scripts/try.ts https://seller.example/api/data --max 0.01 --chain base
+```
+
+本文と鍵は表示しません。`PROBE_EVM_PRIVATE_KEY` / `PROBE_SOLANA_SECRET_KEY` も読みます。
+
+## 開発
+
+```sh
+npm install
+npm run typecheck
+npm test     # すべてオフライン（ローカル HTTP サーバーと RPC モック、使い捨て鍵）
+npm run build
+```
+
+レシートの検証は npm の `@x402jp/delivery-receipt-verify`（kato9292929/delivery-receipt）を使います。
+
+## ライセンス
+
+MIT

package/dist/chains/base.d.ts

@@ -0,0 +1,24 @@
+import { type ChainSearch, type TransferCheck } from "./rpc.js";
+export declare const AUTHORIZATION_USED = "0x98de503528ee59b575ef0c0a2576a82497bfc029a5685b209e9ec333479b10a5";
+export declare const topicAddr: (a: string) => string;
+/** The EIP-3009 authorization in an exact-EVM payload (Permit2 payloads are not supported). */
+export declare function evmAuthorization(payload: any): {
+    nonce: string;
+    signature: string;
+    from: string;
+    to: string;
+    value: string;
+};
+/** Pure: how much USDC this receipt moved from payer (in total) and to payTo, vs the offered amount. */
+export declare function checkBaseTransfer(receipt: any, w: {
+    payer: string;
+    payTo: string;
+    amount: bigint;
+}): TransferCheck;
+/** Poll for a known tx hash's receipt (it can take a moment to be visible). */
+export declare function getBaseReceipt(txHash: string, s: ChainSearch): Promise<any | null>;
+/** The tx that consumed our authorization nonce (searched in the last ~hour of blocks), if any. */
+export declare function findBasePayment(payer: string, nonce: string, s: ChainSearch): Promise<{
+    hash: string;
+    receipt: any;
+} | null>;

package/dist/chains/base.js

@@ -0,0 +1,70 @@
+// Base mainnet: finding and checking an x402 exact-EVM payment (EIP-3009
+// transferWithAuthorization). The payer never sends a tx; the facilitator does, so the
+// payer-side key is the authorization nonce, consumed on chain by USDC's
+// AuthorizationUsed(authorizer, nonce) event. Ported from seller-probe src/chains/base.ts.
+import { USDC } from "../constants.js";
+import { rpc, sleep } from "./rpc.js";
+const TRANSFER = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+export const AUTHORIZATION_USED = "0x98de503528ee59b575ef0c0a2576a82497bfc029a5685b209e9ec333479b10a5";
+export const topicAddr = (a) => "0x" + a.toLowerCase().replace(/^0x/, "").padStart(64, "0");
+/** The EIP-3009 authorization in an exact-EVM payload (Permit2 payloads are not supported). */
+export function evmAuthorization(payload) {
+    const p = payload?.payload;
+    if (!p?.authorization?.nonce || !p?.signature)
+        throw new Error("EVM payload is not an EIP-3009 authorization");
+    return { nonce: p.authorization.nonce, signature: p.signature, from: p.authorization.from, to: p.authorization.to, value: String(p.authorization.value) };
+}
+/** Pure: how much USDC this receipt moved from payer (in total) and to payTo, vs the offered amount. */
+export function checkBaseTransfer(receipt, w) {
+    if (!receipt)
+        return { ok: false, reason: "receipt not found", transferred: null, received_by_pay_to: null };
+    if (receipt.status !== "0x1")
+        return { ok: false, reason: "transaction reverted", transferred: "0", received_by_pay_to: "0" };
+    const usdcTransfers = (receipt.logs ?? []).filter((l) => l.address?.toLowerCase() === USDC.base.toLowerCase() && l.topics?.[0] === TRANSFER && l.topics?.[1]?.toLowerCase() === topicAddr(w.payer));
+    const sum = (ls) => ls.reduce((s, l) => s + BigInt(l.data), 0n);
+    const transferred = sum(usdcTransfers);
+    const toPayTo = sum(usdcTransfers.filter((l) => l.topics?.[2]?.toLowerCase() === topicAddr(w.payTo)));
+    const out = { transferred: transferred.toString(), received_by_pay_to: toPayTo.toString() };
+    if (transferred === 0n)
+        return { ok: false, reason: "no USDC Transfer from payer in receipt", ...out };
+    if (transferred !== w.amount)
+        return { ok: false, reason: `USDC transferred ${transferred} != offered ${w.amount}`, ...out };
+    if (toPayTo !== w.amount)
+        return { ok: false, reason: `USDC to payTo ${toPayTo} != offered ${w.amount}`, ...out };
+    return { ok: true, reason: "USDC transfer payer->payTo matches the 402", ...out };
+}
+/** Poll for a known tx hash's receipt (it can take a moment to be visible). */
+export async function getBaseReceipt(txHash, s) {
+    const until = Date.now() + s.timeoutMs;
+    do {
+        const r = await rpc(s.rpcUrl, "eth_getTransactionReceipt", [txHash]).catch(() => null);
+        if (r)
+            return r;
+        if (Date.now() >= until)
+            break;
+        await sleep(s.pollMs);
+    } while (Date.now() < until);
+    return null;
+}
+/** The tx that consumed our authorization nonce (searched in the last ~hour of blocks), if any. */
+export async function findBasePayment(payer, nonce, s) {
+    const until = Date.now() + s.timeoutMs;
+    do {
+        const latestHex = await rpc(s.rpcUrl, "eth_blockNumber", []).catch(() => null);
+        if (latestHex) {
+            const latest = parseInt(latestHex, 16);
+            const from = Math.max(0, latest - 1800);
+            const logs = await rpc(s.rpcUrl, "eth_getLogs", [
+                { address: USDC.base, fromBlock: "0x" + from.toString(16), toBlock: "0x" + latest.toString(16), topics: [AUTHORIZATION_USED, topicAddr(payer), nonce.toLowerCase()] },
+            ]).catch(() => []);
+            if (logs?.length) {
+                const hash = logs[0].transactionHash;
+                return { hash, receipt: await getBaseReceipt(hash, s) };
+            }
+        }
+        if (Date.now() >= until)
+            break;
+        await sleep(s.pollMs);
+    } while (Date.now() < until);
+    return null;
+}

package/dist/chains/rpc.d.ts

@@ -0,0 +1,17 @@
+export declare function rpc<T = any>(url: string, method: string, params: unknown[], attempts?: number): Promise<T>;
+export declare const sleep: (ms: number) => Promise<unknown>;
+/** Where and how long to look on chain. */
+export type ChainSearch = {
+    rpcUrl: string;
+    timeoutMs: number;
+    pollMs: number;
+};
+/** Outcome of checking one transaction against the offer. Amounts are atomic USDC strings. */
+export type TransferCheck = {
+    ok: boolean;
+    reason: string;
+    /** USDC that left the payer in this tx (null when it could not be read). */
+    transferred: string | null;
+    /** USDC that reached payTo in this tx. */
+    received_by_pay_to: string | null;
+};

package/dist/chains/rpc.js

@@ -0,0 +1,25 @@
+// Minimal JSON-RPC over fetch, with a few retries.
+export async function rpc(url, method, params, attempts = 3) {
+    let last;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            const r = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+                signal: AbortSignal.timeout(20_000),
+            });
+            const j = await r.json();
+            if (j.error)
+                throw new Error(`${method}: ${JSON.stringify(j.error)}`);
+            return j.result;
+        }
+        catch (e) {
+            last = e;
+            if (i < attempts - 1)
+                await sleep(300 * 2 ** i);
+        }
+    }
+    throw last;
+}
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/chains/solana.d.ts

@@ -0,0 +1,29 @@
+import { type ChainSearch, type TransferCheck } from "./rpc.js";
+/** Build a signer from a base58 or JSON-array 64-byte secret key. The key is never kept elsewhere. */
+export declare function solanaSignerFrom(secret: string): Promise<import("@solana/kit").KeyPairSigner<string>>;
+/**
+ * The payer's address and signature inside payload.payload.transaction. The payer is the
+ * signer that has already signed (the facilitator's fee-payer slot is still empty), or
+ * `payer` when given.
+ */
+export declare function payerSignature(payload: any, payer?: string): {
+    payer: string;
+    signature: string;
+};
+/** Pure: how much USDC a jsonParsed getTransaction result moved out of payer and into payTo. */
+export declare function checkSolanaTransfer(tx: any, w: {
+    payer: string;
+    payTo: string;
+    amount: bigint;
+}): TransferCheck;
+/** Poll for a known signature (a settled tx can take a few seconds to be visible at `confirmed`). */
+export declare function getSolanaTx(sig: string, s: ChainSearch): Promise<any | null>;
+/**
+ * Look for a landed tx carrying our own signature among recent transactions that touch
+ * the payer. In an x402 exact-SVM tx the tx id is the fee payer's (facilitator's)
+ * signature, so our signature is matched against every signature of each candidate.
+ */
+export declare function findSolanaPayment(payer: string, payerSig: string, s: ChainSearch, limit?: number): Promise<{
+    signature: string;
+    tx: any;
+} | null>;

package/dist/chains/solana.js

@@ -0,0 +1,93 @@
+// Solana mainnet: the buyer's own signature in an x402 exact-SVM payment tx, finding that
+// tx on chain, and checking the USDC transfer in it. Ported from seller-probe src/chains/solana.ts.
+import bs58 from "bs58";
+import { createKeyPairSignerFromBytes, getBase64Encoder, getTransactionDecoder } from "@solana/kit";
+import { USDC } from "../constants.js";
+import { rpc, sleep } from "./rpc.js";
+/** Build a signer from a base58 or JSON-array 64-byte secret key. The key is never kept elsewhere. */
+export async function solanaSignerFrom(secret) {
+    const t = secret.trim();
+    const bytes = t.startsWith("[") ? Uint8Array.from(JSON.parse(t)) : bs58.decode(t);
+    if (bytes.length !== 64)
+        throw new Error(`Solana secret key must be 64 bytes, got ${bytes.length}`);
+    return createKeyPairSignerFromBytes(bytes);
+}
+function decodeTx(payload) {
+    const b64 = payload?.payload?.transaction;
+    if (typeof b64 !== "string")
+        throw new Error("SVM payload has no payload.transaction");
+    return getTransactionDecoder().decode(getBase64Encoder().encode(b64));
+}
+const signed = (sig) => !!sig && !sig.every((b) => b === 0);
+/**
+ * The payer's address and signature inside payload.payload.transaction. The payer is the
+ * signer that has already signed (the facilitator's fee-payer slot is still empty), or
+ * `payer` when given.
+ */
+export function payerSignature(payload, payer) {
+    const tx = decodeTx(payload);
+    const sigs = tx.signatures;
+    const entry = payer ? [payer, sigs[payer]] : Object.entries(sigs).find(([, s]) => signed(s));
+    if (!entry || !signed(entry[1]))
+        throw new Error("payer signature missing in payment tx");
+    return { payer: entry[0], signature: bs58.encode(entry[1]) };
+}
+/** Pure: how much USDC a jsonParsed getTransaction result moved out of payer and into payTo. */
+export function checkSolanaTransfer(tx, w) {
+    if (!tx)
+        return { ok: false, reason: "transaction not found", transferred: null, received_by_pay_to: null };
+    const delta = (owner) => {
+        const amt = (list) => (list ?? []).filter((b) => b.mint === USDC.solana && b.owner === owner).reduce((s, b) => s + BigInt(b.uiTokenAmount?.amount ?? "0"), 0n);
+        return amt(tx.meta?.postTokenBalances) - amt(tx.meta?.preTokenBalances);
+    };
+    if (tx.meta?.err)
+        return { ok: false, reason: `transaction failed: ${JSON.stringify(tx.meta.err)}`, transferred: "0", received_by_pay_to: "0" };
+    const transferred = -delta(w.payer);
+    const toPayTo = delta(w.payTo);
+    const out = { transferred: transferred.toString(), received_by_pay_to: toPayTo.toString() };
+    if (transferred !== w.amount)
+        return { ok: false, reason: `payer USDC out ${transferred} != offered ${w.amount}`, ...out };
+    if (toPayTo !== w.amount)
+        return { ok: false, reason: `payTo USDC in ${toPayTo} != offered ${w.amount}`, ...out };
+    return { ok: true, reason: "USDC transfer payer->payTo matches the 402", ...out };
+}
+async function getTx(sig, s) {
+    return rpc(s.rpcUrl, "getTransaction", [sig, { encoding: "jsonParsed", commitment: "confirmed", maxSupportedTransactionVersion: 0 }]);
+}
+/** Poll for a known signature (a settled tx can take a few seconds to be visible at `confirmed`). */
+export async function getSolanaTx(sig, s) {
+    const until = Date.now() + s.timeoutMs;
+    do {
+        const tx = await getTx(sig, s).catch(() => null);
+        if (tx)
+            return tx;
+        if (Date.now() >= until)
+            break;
+        await sleep(s.pollMs);
+    } while (Date.now() < until);
+    return null;
+}
+/**
+ * Look for a landed tx carrying our own signature among recent transactions that touch
+ * the payer. In an x402 exact-SVM tx the tx id is the fee payer's (facilitator's)
+ * signature, so our signature is matched against every signature of each candidate.
+ */
+export async function findSolanaPayment(payer, payerSig, s, limit = 20) {
+    const seen = new Set();
+    const until = Date.now() + s.timeoutMs;
+    do {
+        const sigs = await rpc(s.rpcUrl, "getSignaturesForAddress", [payer, { limit, commitment: "confirmed" }]).catch(() => []);
+        for (const x of sigs ?? []) {
+            if (seen.has(x.signature))
+                continue;
+            seen.add(x.signature);
+            const tx = await getTx(x.signature, s).catch(() => null);
+            if (tx?.transaction?.signatures?.includes(payerSig))
+                return { signature: tx.transaction.signatures[0] ?? x.signature, tx };
+        }
+        if (Date.now() >= until)
+            break;
+        await sleep(s.pollMs);
+    } while (Date.now() < until);
+    return null;
+}

package/dist/constants.d.ts

@@ -0,0 +1,21 @@
+export type Chain = "base" | "solana";
+export type ChainChoice = Chain | "any";
+/** CAIP-2 ids (x402 v2) and v1 network names that count as each chain's mainnet. */
+export declare const NETWORKS: Record<Chain, {
+    caip2: `${string}:${string}`;
+    v1: string[];
+}>;
+/** Official USDC (Circle). Compared case-insensitively on Base. */
+export declare const USDC: Record<Chain, string>;
+/** Order used when the caller asks for chain "any". */
+export declare const CHAIN_PREFERENCE: Chain[];
+export declare const DEFAULT_PROBE_URL = "https://probe.x402jp.com";
+export declare const DEFAULT_RPC: Record<Chain, string>;
+export declare const PROBE_TIMEOUT_MS = 5000;
+export declare const REQUEST_TIMEOUT_MS = 60000;
+export declare const DEFAULT_FIND_TIMEOUT_MS = 90000;
+export declare function chainOf(network: string | undefined): Chain | null;
+/** Package version, read once from package.json (works from both src/ and dist/). */
+export declare const VERSION: string;
+export declare const SDK_ID: string;
+export declare const USER_AGENT: string;

package/dist/constants.js

@@ -0,0 +1,43 @@
+// Chains, official USDC and defaults. Mainnet only: Base and Solana.
+import { readFileSync } from "node:fs";
+/** CAIP-2 ids (x402 v2) and v1 network names that count as each chain's mainnet. */
+export const NETWORKS = {
+    base: { caip2: "eip155:8453", v1: ["base", "base-mainnet"] },
+    solana: { caip2: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", v1: ["solana", "solana-mainnet"] },
+};
+/** Official USDC (Circle). Compared case-insensitively on Base. */
+export const USDC = {
+    base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    solana: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+};
+/** Order used when the caller asks for chain "any". */
+export const CHAIN_PREFERENCE = ["base", "solana"];
+export const DEFAULT_PROBE_URL = "https://probe.x402jp.com";
+export const DEFAULT_RPC = {
+    base: "https://mainnet.base.org",
+    solana: "https://api.mainnet-beta.solana.com",
+};
+export const PROBE_TIMEOUT_MS = 5_000;
+export const REQUEST_TIMEOUT_MS = 60_000;
+export const DEFAULT_FIND_TIMEOUT_MS = 90_000;
+export function chainOf(network) {
+    if (!network)
+        return null;
+    const n = network.toLowerCase();
+    for (const c of Object.keys(NETWORKS)) {
+        if (n === NETWORKS[c].caip2.toLowerCase() || NETWORKS[c].v1.includes(n))
+            return c;
+    }
+    return null;
+}
+/** Package version, read once from package.json (works from both src/ and dist/). */
+export const VERSION = (() => {
+    try {
+        return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+export const SDK_ID = `@x402jp/safe-buy@${VERSION}`;
+export const USER_AGENT = `x402jp-safe-buy/${VERSION}`;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { safeBuy, checkSeller, type SafeBuyOptions, type SafeBuyResult, type CheckOptions, type CheckResult, type BuyInput, type Offer, type Outcome, type Stage, type StageName, type AttemptRecord, type ProbeInfo, } from "./safe-buy.js";
+export { verifyReceipt, type VerifyReceiptArgs, type ReceiptCheck } from "./receipt.js";
+export type { Signer, PayerKey } from "./pay.js";
+export type { ProbeDoc } from "./probe.js";
+export type { Report } from "./report.js";
+export { type Price, usdToAtomic, atomicToUsd } from "./price.js";
+export { type Chain, type ChainChoice, NETWORKS, USDC, VERSION } from "./constants.js";
+export { parse402, inputRequirement, selectAccept, isOfficialUsdc, type Accept, type Parsed402, type InputRequirement } from "./x402.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// @x402jp/safe-buy: buy from an x402 (HTTP 402, USDC) seller safely.
+export { safeBuy, checkSeller, } from "./safe-buy.js";
+export { verifyReceipt } from "./receipt.js";
+export { usdToAtomic, atomicToUsd } from "./price.js";
+export { NETWORKS, USDC, VERSION } from "./constants.js";
+export { parse402, inputRequirement, selectAccept, isOfficialUsdc } from "./x402.js";

package/dist/mcp-bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp-bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// stdio entry point of the x402-safe-buy MCP server. stdout carries the protocol only.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createSafeBuyMcpServer } from "./mcp.js";
+const server = createSafeBuyMcpServer();
+await server.connect(new StdioServerTransport());

package/dist/mcp.d.ts

@@ -0,0 +1,16 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type SafeBuyOptions, type SafeBuyResult } from "./safe-buy.js";
+export declare const BODY_LIMIT_BYTES: number;
+/** Default ceiling on any maxPrice an agent passes to safe_buy (USD). Override with SAFE_BUY_MAX_PRICE_CAP. */
+export declare const DEFAULT_MAX_PRICE_CAP = "0.10";
+export type McpConfig = {
+    /** Where keys and settings are read from (default process.env). */
+    env?: Record<string, string | undefined>;
+    /** Extra safeBuy options for every call (tests: rpc, findTimeoutMs, pollIntervalMs). Keys are not accepted here. */
+    defaults?: Omit<Partial<SafeBuyOptions>, "signer" | "client" | "maxPrice">;
+};
+/** Body as UTF-8 text (truncated) when it decodes, else base64 when small enough. */
+export declare function bodyForAgent(body: Uint8Array | null): Record<string, unknown>;
+/** The evidence fields of a purchase plus the body in agent-readable form. */
+export declare function safeBuyView(r: SafeBuyResult): Record<string, unknown>;
+export declare function createSafeBuyMcpServer(config?: McpConfig): McpServer;

package/dist/mcp.js

@@ -0,0 +1,131 @@
+// MCP server exposing check_seller, safe_buy and verify_receipt. Signing keys come only
+// from the server's environment (SAFE_BUY_EVM_PRIVATE_KEY / SAFE_BUY_SOLANA_SECRET_KEY),
+// never from tool arguments, and are never echoed back.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { VERSION } from "./constants.js";
+import { atomicToUsd, usdToAtomic } from "./price.js";
+import { verifyReceipt } from "./receipt.js";
+import { checkSeller, safeBuy } from "./safe-buy.js";
+export const BODY_LIMIT_BYTES = 50 * 1024;
+/** Default ceiling on any maxPrice an agent passes to safe_buy (USD). Override with SAFE_BUY_MAX_PRICE_CAP. */
+export const DEFAULT_MAX_PRICE_CAP = "0.10";
+const chain = z.enum(["base", "solana", "any"]).optional().describe('Chain to pay on (default "any": Base, then Solana)');
+const price = z.union([z.number().positive(), z.string()]);
+const input = z
+    .object({
+    method: z.string().optional(),
+    query: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    body: z.any().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+})
+    .optional()
+    .describe("Request input for endpoints that need more than a bare GET");
+const json = (v) => ({ content: [{ type: "text", text: JSON.stringify(v, null, 2) }] });
+const fail = (msg) => ({ content: [{ type: "text", text: msg }], isError: true });
+/** Body as UTF-8 text (truncated) when it decodes, else base64 when small enough. */
+export function bodyForAgent(body) {
+    if (!body)
+        return { body_bytes: 0 };
+    const truncated = body.length > BODY_LIMIT_BYTES;
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(body.subarray(0, BODY_LIMIT_BYTES));
+        return { body_bytes: body.length, body_text: text, body_truncated: truncated };
+    }
+    catch {
+        // A cut in the middle of a multi-byte character is still text.
+        if (truncated) {
+            const t = new TextDecoder("utf-8", { fatal: false }).decode(body.subarray(0, BODY_LIMIT_BYTES));
+            if (!/�/.test(t.slice(0, -1)))
+                return { body_bytes: body.length, body_text: t.replace(/�$/, ""), body_truncated: true };
+        }
+        return truncated
+            ? { body_bytes: body.length, body_binary: true, body_truncated: true }
+            : { body_bytes: body.length, body_base64: Buffer.from(body).toString("base64"), body_binary: true };
+    }
+}
+/** The evidence fields of a purchase plus the body in agent-readable form. */
+export function safeBuyView(r) {
+    const { body, probe, ...rest } = r;
+    return { ...rest, probe_status: probe.status, ...bodyForAgent(body) };
+}
+export function createSafeBuyMcpServer(config = {}) {
+    const env = config.env ?? process.env;
+    const server = new McpServer({ name: "x402-safe-buy", version: VERSION });
+    const probeUrl = config.defaults?.probeUrl || env.SAFE_BUY_PROBE_URL || undefined;
+    server.registerTool("check_seller", {
+        title: "Check an x402 seller (no payment)",
+        description: "Looks up the seller at the x402 Seller Probe, fetches the 402 offer and checks price/input requirements. Never pays.",
+        inputSchema: { url: z.string().url(), chain, maxPrice: price.optional().describe("USD cap, e.g. 0.01 or \"$0.01\""), input },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        try {
+            return json(await checkSeller(a.url, { ...config.defaults, probeUrl, chain: a.chain, maxPrice: a.maxPrice, input: a.input }));
+        }
+        catch (e) {
+            return fail(`check_seller failed: ${e?.message ?? e}`);
+        }
+    });
+    server.registerTool("safe_buy", {
+        title: "Buy one x402 call safely (spends USDC)",
+        description: "Pays an x402 seller in USDC only if the Probe record, the 402 offer and the price pass; reconciles the payment on chain, refetches with a Delivery Receipt if needed. Spends real money.",
+        inputSchema: {
+            url: z.string().url(),
+            maxPrice: price.describe("Required USD cap, e.g. 0.01 or \"$0.01\""),
+            chain,
+            input,
+            report: z.boolean().optional().describe("Send an anonymized outcome report to the Probe (default false)"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        const signer = { evmPrivateKey: env.SAFE_BUY_EVM_PRIVATE_KEY || undefined, solanaSecretKey: env.SAFE_BUY_SOLANA_SECRET_KEY || undefined };
+        if (!signer.evmPrivateKey && !signer.solanaSecretKey)
+            return fail("safe_buy: no wallet configured on the server (SAFE_BUY_EVM_PRIVATE_KEY / SAFE_BUY_SOLANA_SECRET_KEY)");
+        let cap, max;
+        try {
+            cap = usdToAtomic(env.SAFE_BUY_MAX_PRICE_CAP || DEFAULT_MAX_PRICE_CAP);
+            max = usdToAtomic(a.maxPrice);
+        }
+        catch (e) {
+            return fail(`safe_buy: ${e?.message ?? e}`);
+        }
+        if (max > cap)
+            return fail(`safe_buy: maxPrice ${atomicToUsd(max)} is above the server cap ${atomicToUsd(cap)} (SAFE_BUY_MAX_PRICE_CAP)`);
+        try {
+            const r = await safeBuy(a.url, {
+                ...config.defaults,
+                probeUrl,
+                maxPrice: a.maxPrice,
+                chain: a.chain,
+                input: a.input,
+                report: a.report === true,
+                signer,
+                rpc: { base: env.BASE_RPC_URL, solana: env.SOLANA_RPC_URL, ...config.defaults?.rpc },
+            });
+            return json(safeBuyView(r));
+        }
+        catch (e) {
+            return fail(`safe_buy failed: ${e?.message ?? e}`);
+        }
+    });
+    server.registerTool("verify_receipt", {
+        title: "Verify an x402 Delivery Receipt",
+        description: "Fetches the seller's /.well-known/x402-receipt.json and verifies an X-Delivery-Receipt against the body bytes and payment id.",
+        inputSchema: {
+            url: z.string().url(),
+            receipt: z.string().min(1).describe("X-Delivery-Receipt header value"),
+            body_base64: z.string().describe("Exact response body, base64"),
+            payment_id: z.string().optional().describe("Solana tx signature or Base EIP-3009 nonce"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (a) => {
+        try {
+            const r = await verifyReceipt({ url: a.url, header: a.receipt, body: new Uint8Array(Buffer.from(a.body_base64, "base64")), paymentId: a.payment_id ?? null });
+            return json(r);
+        }
+        catch (e) {
+            return fail(`verify_receipt failed: ${e?.message ?? e}`);
+        }
+    });
+    return server;
+}