@aifinpay/mcp 2.12.2 → 2.14.1

package/dist/tools/directory.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Directory tools — the READ-ONLY surface submitted to the OpenAI ChatGPT App
+ * Directory. Every tool here is a thin wrapper over a public `api.aifinpay.io`
+ * GET endpoint: no agent identity, no keys, no money movement, no auth. This is
+ * what makes the directory app reviewable (OpenAI prohibits payment/crypto
+ * EXECUTION in directory apps — see Obsidian/32). Execution tools live only on
+ * the full BYO-MCP connector (`server.ts`), never here.
+ *
+ * Each tool declares `readOnlyHint: true`, an `outputSchema`, and ALWAYS returns
+ * `structuredContent` matching it (the audit found 4 connector tools that declare
+ * outputSchema but return only text — Apps SDK validation may reject that; we
+ * don't repeat it).
+ */
+/** Public API base. Defaults to production; override with AIFINPAY_API_BASE. */
+export declare const DIRECTORY_API_BASE: string;
+export interface DirectoryContext {
+    apiBase: string;
+    timeoutMs: number;
+    log: (level: "info" | "warn" | "error", msg: string) => void;
+}
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+};
+export declare function directoryTools(): ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name?: undefined;
+            chain?: undefined;
+            amount?: undefined;
+            asset?: undefined;
+            pubkey?: undefined;
+            address?: undefined;
+        };
+        required?: undefined;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        type: string;
+        properties: {
+            providers: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            covered?: undefined;
+            total_seats?: undefined;
+            leaderboard?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            chain?: undefined;
+            amount?: undefined;
+            asset?: undefined;
+            pubkey?: undefined;
+            address?: undefined;
+        };
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        type: string;
+        properties?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name?: undefined;
+            chain?: undefined;
+            amount?: undefined;
+            asset?: undefined;
+            pubkey?: undefined;
+            address?: undefined;
+        };
+        required?: undefined;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        type: string;
+        properties?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name?: undefined;
+            chain?: undefined;
+            amount?: undefined;
+            asset?: undefined;
+            pubkey?: undefined;
+            address?: undefined;
+        };
+        required?: undefined;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        type: string;
+        properties: {
+            providers?: undefined;
+            covered: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            total_seats?: undefined;
+            leaderboard?: undefined;
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name?: undefined;
+            chain?: undefined;
+            amount?: undefined;
+            asset?: undefined;
+            pubkey?: undefined;
+            address?: undefined;
+        };
+        required?: undefined;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        type: string;
+        properties: {
+            providers?: undefined;
+            covered?: undefined;
+            total_seats: {
+                type: string;
+            };
+            leaderboard: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+        };
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name?: undefined;
+            chain: {
+                type: string;
+                enum: string[];
+            };
+            amount: {
+                type: string;
+                description: string;
+            };
+            asset: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            pubkey?: undefined;
+            address?: undefined;
+        };
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        properties?: undefined;
+        type: string;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name?: undefined;
+            chain?: undefined;
+            amount?: undefined;
+            asset?: undefined;
+            pubkey: {
+                type: string;
+                description: string;
+            };
+            address?: undefined;
+        };
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        properties?: undefined;
+        type: string;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name?: undefined;
+            chain?: undefined;
+            amount?: undefined;
+            asset?: undefined;
+            pubkey?: undefined;
+            address: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    outputSchema: {
+        properties?: undefined;
+        type: string;
+    };
+})[];
+export declare function runDirectoryTool(ctx: DirectoryContext, name: string, args: Record<string, unknown>): Promise<ToolResult>;
+export {};
+//# sourceMappingURL=directory.d.ts.map

package/dist/tools/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../../src/tools/directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,QAAkF,CAAC;AAElH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAED,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAyCF,wBAAgB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;gBAiBP,IAAI;gBAAW,KAAK;oBAAI,IAAI;;;;;;;;;;;;;;;gBAavC,IAAI;gBACJ,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBA0BF,IAAI;gBAAW,KAAK;oBAAI,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAsBxB,IAAI;;;gBACJ,IAAI;gBAAW,KAAK;oBAAI,IAAI;;;;;;;;;;;;;gBAalC,IAAI;gBAAY,IAAI;;;gBAE3B,IAAI;gBACJ,WAAW;;;gBAKX,IAAI;gBACJ,IAAI;gBACJ,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAmBX,IAAI;gBACJ,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAgBX,IAAI;gBACJ,WAAW;;;;;;;;;;;;;;KAStB;AAID,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC,CAsDrB"}

package/dist/tools/directory.js

@@ -0,0 +1,253 @@
+/**
+ * Directory tools — the READ-ONLY surface submitted to the OpenAI ChatGPT App
+ * Directory. Every tool here is a thin wrapper over a public `api.aifinpay.io`
+ * GET endpoint: no agent identity, no keys, no money movement, no auth. This is
+ * what makes the directory app reviewable (OpenAI prohibits payment/crypto
+ * EXECUTION in directory apps — see Obsidian/32). Execution tools live only on
+ * the full BYO-MCP connector (`server.ts`), never here.
+ *
+ * Each tool declares `readOnlyHint: true`, an `outputSchema`, and ALWAYS returns
+ * `structuredContent` matching it (the audit found 4 connector tools that declare
+ * outputSchema but return only text — Apps SDK validation may reject that; we
+ * don't repeat it).
+ */
+/** Public API base. Defaults to production; override with AIFINPAY_API_BASE. */
+export const DIRECTORY_API_BASE = (process.env.AIFINPAY_API_BASE || "https://api.aifinpay.io").replace(/\/$/, "");
+function ok(data) {
+    // structuredContent must be an object; wrap bare arrays/primitives.
+    const structured = data && typeof data === "object" && !Array.isArray(data) ? data : { result: data };
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        structuredContent: structured,
+    };
+}
+function fail(msg) {
+    return { isError: true, content: [{ type: "text", text: msg }] };
+}
+async function apiGet(ctx, path) {
+    const url = `${ctx.apiBase}${path}`;
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), ctx.timeoutMs);
+    try {
+        const resp = await fetch(url, {
+            headers: { accept: "application/json" },
+            signal: ctrl.signal,
+        });
+        if (!resp.ok) {
+            return fail(`upstream ${resp.status} for ${path}`);
+        }
+        const data = await resp.json();
+        return ok(data);
+    }
+    catch (e) {
+        return fail(`request failed for ${path}: ${e.message}`);
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+const RO = { readOnlyHint: true, openWorldHint: false, destructiveHint: false };
+// ── Tool definitions ───────────────────────────────────────────────────────
+export function directoryTools() {
+    return [
+        {
+            name: "list_providers",
+            description: "List the AI services available through AiFinPay (e.g. web search, " +
+                "image generation, LLM inference) with their per-call price and " +
+                "supported networks. Read-only; returns the public provider catalog.",
+            inputSchema: { type: "object", properties: {} },
+            annotations: RO,
+            // Permissive: the upstream provider catalog is the source of truth and its
+            // leaf field types vary (e.g. price_usd may be a number or a string for
+            // range/tier pricing). The MCP client validates structuredContent against
+            // this schema strictly, so we only assert the top-level shape.
+            outputSchema: {
+                type: "object",
+                properties: {
+                    providers: { type: "array", items: { type: "object" } },
+                },
+            },
+        },
+        {
+            name: "provider_info",
+            description: "Get the details of one AiFinPay provider by name (price, supported " +
+                "networks, service type, homepage). Read-only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Provider name, e.g. 'exa', 'venice', 'io-net'.",
+                    },
+                },
+                required: ["name"],
+            },
+            annotations: RO,
+            outputSchema: { type: "object" },
+        },
+        {
+            name: "provider_status",
+            description: "Report which AiFinPay provider bridges are currently reachable " + "(up/down). Read-only health view.",
+            inputSchema: { type: "object", properties: {} },
+            annotations: RO,
+            outputSchema: { type: "object" },
+        },
+        {
+            name: "service_coverage",
+            description: "Show which categories of AI service (search, compute, …) AiFinPay " +
+                "currently covers and the providers in each. Read-only.",
+            inputSchema: { type: "object", properties: {} },
+            annotations: RO,
+            outputSchema: {
+                type: "object",
+                properties: {
+                    covered: { type: "array", items: { type: "object" } },
+                },
+            },
+        },
+        {
+            name: "network_stats",
+            description: "Return public protocol statistics: supported networks, number of " +
+                "active agents, total settled volume, and active providers. Read-only.",
+            inputSchema: { type: "object", properties: {} },
+            annotations: RO,
+            outputSchema: { type: "object" },
+        },
+        {
+            name: "leaderboard",
+            description: "Return the public on-chain leaderboard of AiFinPay agents ranked by " + "settled volume. Read-only.",
+            inputSchema: { type: "object", properties: {} },
+            annotations: RO,
+            outputSchema: {
+                type: "object",
+                properties: {
+                    total_seats: { type: "number" },
+                    leaderboard: { type: "array", items: { type: "object" } },
+                },
+            },
+        },
+        {
+            name: "quote_cost",
+            description: "Preview the fee-on-top breakdown (merchant amount + protocol fee + " +
+                "creator fee + total) for a given price, WITHOUT making any payment. " +
+                "Read-only price calculator.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    chain: { type: "string", enum: ["solana", "polygon"] },
+                    amount: {
+                        type: "string",
+                        description: "Merchant's quoted price in base units: lamports (Solana SOL), " +
+                            "wei (Polygon POL), or 6-decimal units (Polygon USDC/USDT).",
+                    },
+                    asset: {
+                        type: "string",
+                        enum: ["SOL", "POL", "USDC", "USDT"],
+                        description: "Settlement asset. Defaults to SOL on Solana, POL on Polygon. " +
+                            "Use USDC/USDT for Polygon stablecoin quotes.",
+                    },
+                },
+                required: ["chain", "amount"],
+            },
+            annotations: RO,
+            outputSchema: { type: "object" },
+        },
+        {
+            name: "verify_passport",
+            description: "Check whether an agent public key holds an AiFinPay AgentPassport and " +
+                "return its on-chain status. Read-only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    pubkey: {
+                        type: "string",
+                        description: "Agent public key (Solana base58 or EVM address).",
+                    },
+                },
+                required: ["pubkey"],
+            },
+            annotations: RO,
+            outputSchema: { type: "object" },
+        },
+        {
+            name: "agent_profile",
+            description: "Return the public profile and activity summary for an AiFinPay agent " + "by its address. Read-only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    address: {
+                        type: "string",
+                        description: "Agent address (EVM 0x… or Solana base58).",
+                    },
+                },
+                required: ["address"],
+            },
+            annotations: RO,
+            outputSchema: { type: "object" },
+        },
+    ];
+}
+// ── Dispatch ────────────────────────────────────────────────────────────────
+export async function runDirectoryTool(ctx, name, args) {
+    switch (name) {
+        case "list_providers":
+            return apiGet(ctx, "/providers");
+        case "provider_info": {
+            const n = String(args.name ?? "").trim();
+            if (!n)
+                return fail("missing required arg: name");
+            return apiGet(ctx, `/providers/${encodeURIComponent(n)}`);
+        }
+        case "provider_status":
+            return apiGet(ctx, "/providers/status");
+        case "service_coverage":
+            return apiGet(ctx, "/registry/coverage");
+        case "network_stats":
+            return apiGet(ctx, "/network-stats");
+        case "leaderboard":
+            return apiGet(ctx, "/leaderboard");
+        case "quote_cost": {
+            const chain = String(args.chain ?? "")
+                .trim()
+                .toLowerCase();
+            const amount = String(args.amount ?? "").trim();
+            const asset = String(args.asset ?? "")
+                .trim()
+                .toUpperCase();
+            if (!chain || !amount)
+                return fail("missing required args: chain, amount");
+            const qs = new URLSearchParams();
+            if (chain === "solana") {
+                qs.set("merchant_amount_lamports", amount);
+            }
+            else if (chain === "polygon") {
+                if (asset === "USDC" || asset === "USDT") {
+                    qs.set("merchant_amount_units", amount);
+                    qs.set("asset", asset);
+                }
+                else {
+                    qs.set("merchant_amount_wei", amount);
+                }
+            }
+            else {
+                return fail("chain must be 'solana' or 'polygon'");
+            }
+            return apiGet(ctx, `/b2b/quote-split?${qs.toString()}`);
+        }
+        case "verify_passport": {
+            const pk = String(args.pubkey ?? "").trim();
+            if (!pk)
+                return fail("missing required arg: pubkey");
+            return apiGet(ctx, `/passport/${encodeURIComponent(pk)}`);
+        }
+        case "agent_profile": {
+            const addr = String(args.address ?? "").trim();
+            if (!addr)
+                return fail("missing required arg: address");
+            return apiGet(ctx, `/network/agents/${encodeURIComponent(addr)}`);
+        }
+        default:
+            return fail(`unknown directory tool: ${name}`);
+    }
+}
+//# sourceMappingURL=directory.js.map

package/dist/tools/directory.js.map

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

package/dist/tools/payable-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payable-fetch.d.ts","sourceRoot":"","sources":["../../src/tools/payable-fetch.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAmBhD,wBAAgB,gBAAgB;IAE5B,IAAI;IACJ,WAAW;IAEX,WAAW;QACT,IAAI;QACJ,UAAU;YACR,GAAG;gBACD,IAAI;gBACJ,WAAW;;YAGb,cAAc;gBACZ,IAAI;gBACJ,gBAAgB;gBAChB,WAAW;;YAEb,KAAK;gBACH,IAAI;gBACJ,IAAI;gBACJ,WAAW;;YAGb,oBAAoB;gBAClB,IAAI;gBACJ,OAAO;gBACP,WAAW;;;QAIf,QAAQ;QACR,oBAAoB;;IAEtB,WAAW;QAAI,YAAY;QAAS,aAAa;QAAQ,eAAe;;EAE3E;AAED,2FAA2F;AAC3F,wBAAsB,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GA+ZpF"}
+{"version":3,"file":"payable-fetch.d.ts","sourceRoot":"","sources":["../../src/tools/payable-fetch.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAmBhD,wBAAgB,gBAAgB;IAE5B,IAAI;IACJ,WAAW;IAEX,WAAW;QACT,IAAI;QACJ,UAAU;YACR,GAAG;gBACD,IAAI;gBACJ,WAAW;;YAGb,cAAc;gBACZ,IAAI;gBACJ,gBAAgB;gBAChB,WAAW;;YAEb,KAAK;gBACH,IAAI;gBACJ,IAAI;gBACJ,WAAW;;YAGb,oBAAoB;gBAClB,IAAI;gBACJ,OAAO;gBACP,WAAW;;;QAIf,QAAQ;QACR,oBAAoB;;IAEtB,WAAW;QAAI,YAAY;QAAS,aAAa;QAAQ,eAAe;;EAE3E;AAED,2FAA2F;AAC3F,wBAAsB,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GAyapF"}

package/dist/tools/payable-fetch.js

@@ -17,7 +17,7 @@ const HOSTED_GATEWAY_ORIGIN = "https://gateway.aifinpay.io";
 export function payableFetchTool() {
     return {
         name: "payable_fetch",
-        description: 'Fetch a GET resource from an AiFinPay merchant, paying its AIFP-1 402 when needed. Always listed: until a persistent wallet exists (npx @aifinpay/mcp init, then agent_reload) it signs nothing and returns the payment_setup_status checklist with the one next step. Payments are on by default within a built-in ceiling of $5 per payment and $20 per 24 hours (the owner can only lower it in env; the working limits are the dashboard Controls after agent_claim_self) and only ever reach a merchant registered with AiFinPay, through a quote signed by the AiFinPay backend; a 402 never chooses who is paid. Without AIFINPAY_GATEWAY_ORIGINS it pays only a merchant whose site AiFinPay reports as DNS-verified, on that very site (or through the AiFinPay hosted gateway); with it, only the origins the owner listed; AIFINPAY_PAYMENTS_ENABLED=0 turns payments off.  Buys a prepaid batch through verified v1.4 on the chain the owner set in AIFINPAY_PAY_CHAIN (Polygon by default; other supported networks require explicit owner selection) — in its native currency (POL, SOL, ETH, AVAX, BNB or XRP), or in the stablecoin the owner set in AIFINPAY_PAY_ASSET (e.g. USDC; gas is still native) — within owner limits, then reuses its receipt. With scope "merchant" one batch covers every path on the site. Pending payments are recovered without sending another transaction. Other payment protocols are unsupported.',
+        description: 'Fetch a GET resource from an AiFinPay merchant, paying its AIFP-1 402 when needed. Always listed: until a persistent wallet exists (npx @aifinpay/mcp init, then agent_reload) it signs nothing and returns the payment_setup_status checklist with the one next step. Payments are on by default within a built-in ceiling of $5 per payment and $20 per 24 hours (the owner can only lower it in env; the working limits are the dashboard Controls after agent_claim_self) and only ever reach a merchant registered with AiFinPay, through a quote signed by the AiFinPay backend; a 402 never chooses who is paid. Without AIFINPAY_GATEWAY_ORIGINS it pays only a merchant whose site AiFinPay reports as DNS-verified, on that very site (or through the AiFinPay hosted gateway); with it, only the origins the owner listed; AIFINPAY_PAYMENTS_ENABLED=0 turns payments off.  Buys a prepaid batch through verified v1.4 on the chain the owner set in AIFINPAY_PAY_CHAIN (Polygon by default; other supported networks require explicit owner selection) — in its native currency (POL, SOL, ETH, AVAX, BNB or XRP), or in the stablecoin the owner set in AIFINPAY_PAY_ASSET (e.g. USDC; gas is still native; on Arc only USDC, which is also its gas) — within owner limits, then reuses its receipt. With scope "merchant" one batch covers every path on the site. Pending payments are recovered without sending another transaction. Other payment protocols are unsupported.',
         inputSchema: {
             type: "object",
             properties: {
@@ -98,6 +98,8 @@ export async function runPayableFetch(ctx, args) {
         const parsed = parseGatewayUrl(url.href, origins, pathMode);
         const pay = chain;
         const payAsset = ctx.config.payAsset ?? pay.native;
+        // On Arc the native symbol names the USDC token: always the token path.
+        const stablePay = payAsset !== pay.native || pay.stablecoinOnly === true;
         const rpc = ctx.config.rpcUrl ?? pay.defaultRpc;
         return await store.exclusive(async () => {
             state = store.read();
@@ -301,12 +303,12 @@ export async function runPayableFetch(ctx, args) {
                         : {
                             v14: {
                                 chain: pay.name,
-                                ...(payAsset !== pay.native ? { asset: payAsset } : {}),
+                                ...(stablePay ? { asset: payAsset } : {}),
                                 maxGasWei: feeCap,
                                 onPrepared: async (prepared) => {
                                     await confirmPayee(prepared.quote.merchant_id);
                                     let usd;
-                                    if (payAsset !== pay.native) {
+                                    if (stablePay) {
                                         if (prepared.asset !== payAsset)
                                             throw new Error("Prepared payment is not in the configured asset");
                                         usd = Number(prepared.quote.amount);
@@ -395,7 +397,15 @@ export async function runPayableFetch(ctx, args) {
                         : ". This merchant id cannot be confirmed through this tool."));
         }
         if (!state?.pending && error instanceof UnverifiedMerchantSiteError) {
-            return errorResult(`${error.message} Without an owner allowlist, payable_fetch pays only a merchant that verified its site with AiFinPay, on that site. Tell the owner; the agent cannot approve this payee itself.`);
+            // Name the ways forward, so neither the agent nor the owner improvises a
+            // third one: another tool, a direct transfer or a retry loop.
+            const noOtherWay = "Do not try another way to pay this site: no other tool, SDK call or direct transfer.";
+            const allowlist = `add ${error.origin} to AIFINPAY_GATEWAY_ORIGINS in this MCP server's env (comma-separated https origins; once it is set, only the listed sites are paid) and restart the MCP client`;
+            return errorResult(error.kind === "unconfirmed"
+                ? `${error.message} The AiFinPay lookup of this merchant failed. Try once more in a minute; if it fails again, stop and tell the owner. ${noOtherWay}`
+                : error.kind === "other_site"
+                    ? `${error.message} The site being paid for is not the one this merchant verified, so this 402 may be steering the payment to someone else. Do not retry. ${noOtherWay} Tell the owner; only if they know ${error.origin} belongs to this merchant should they ${allowlist}.`
+                    : `${error.message} Do not retry. ${noOtherWay} Tell the owner there are two fixes: the merchant verifies this site's domain with AiFinPay (dash.aifinpay.io → Sites → DNS TXT record), or, if the owner knows and trusts ${error.origin}, they ${allowlist}. Then retry once.`);
         }
         if (!state?.pending && error instanceof Aifp1GatewayRetiredError) {
             return errorResult(`${error.site} is retired: the gateway no longer serves this site (410 gateway_retired). Nothing was quoted or paid. Do not retry this request or pay for it again; tell the owner.`);