@cryptoapis-io/mcp-x402-pay 0.1.2 → 0.2.0

package/README.md

@@ -3,9 +3,12 @@
 > **This is the BUYER side of x402** — the tool an agent uses to *spend* (pay for a resource). Merchants
 > who want to *charge* for an API use the middleware SDK (`@cryptoapis-io/x402-merchant-sdk`), not an MCP tool.
 
-An MCP server that lets an AI agent **pay x402-gated HTTP endpoints**. One tool, `x402_pay`: it fetches a
-URL and, if the server returns `402 Payment Required`, it authorizes the payment via the CryptoAPIs buyer
-service, **signs locally**, retries, and returns the paid response.
+An MCP server that lets an AI agent **find and pay** x402-gated HTTP endpoints.
+
+- **`x402_pay`** — fetches a URL and, if the server returns `402 Payment Required`, authorizes the payment
+  via the CryptoAPIs buyer service, **signs locally**, retries, and returns the paid response.
+- **`x402_discover`** — browses the facilitator's catalogue of x402 resources and their prices, so an agent
+  can *find* a paid API instead of only calling one it was handed.
 
 **Non-custodial:** the private key is passed per request and never leaves the process (no HTTP server —
 stdio only).
@@ -53,6 +56,24 @@ bare name — and exactly one of `address` (any chain; **required for Solana/Kas
 Returns `{ status, paid, body, settlement? }`. On a 402 with no acceptable option (or over `maxAmount`),
 `paid:false` with a `reason` — nothing is signed or paid.
 
+## Tool: `x402_discover`
+
+Browse the x402 "Bazaar" — the registered x402 resources and what each charges
+([spec §8](https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md)).
+
+| Input | Required | Description |
+|---|---|---|
+| `type` | | filter by resource type, e.g. `"http"` |
+| `limit` | | page size, 1–100 (default 20) |
+| `offset` | | rows to skip, for paging (default 0) |
+| `facilitatorBaseUrl` | | override the facilitator (QA/local) |
+
+Returns `{ resources: [{ resource, type, x402Version, accepts, lastUpdated, metadata? }], pagination }`.
+
+**Public — no API key, no wallet, spends nothing**, so it is always safe to call. Note `accepts[].amount`
+is in **atomic units** (USDC 6-decimals: `"10000"` = $0.01) — convert before quoting a price to a user.
+Pass a chosen `resource` to `x402_pay` to actually buy it.
+
 ## Flow
 
 1. `fetch(url)`. Not 402 → return it.

package/dist/tools/index.d.ts

@@ -46,5 +46,20 @@ export declare const tools: readonly [import("./types.js").McpX402ToolDef<import
     allowedNetworks?: string[] | undefined;
     buyerBaseUrl?: string | undefined;
     maxAmount?: string | undefined;
+}>>, import("./types.js").McpX402ToolDef<import("zod").ZodObject<{
+    type: import("zod").ZodOptional<import("zod").ZodString>;
+    limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    offset: import("zod").ZodOptional<import("zod").ZodNumber>;
+    facilitatorBaseUrl: import("zod").ZodOptional<import("zod").ZodString>;
+}, "strip", import("zod").ZodTypeAny, {
+    type?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    facilitatorBaseUrl?: string | undefined;
+}, {
+    type?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    facilitatorBaseUrl?: string | undefined;
 }>>];
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAA2C,CAAC"}

package/dist/tools/index.js

@@ -1,3 +1,4 @@
 import { x402PayTool } from "./x402-pay/index.js";
-export const tools = [x402PayTool];
+import { x402DiscoverTool } from "./x402-discover/index.js";
+export const tools = [x402PayTool, x402DiscoverTool];
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,WAAW,CAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,gBAAgB,CAAU,CAAC"}

package/dist/tools/x402-discover/index.d.ts

@@ -0,0 +1,4 @@
+import { X402DiscoverSchema } from "./schema.js";
+import type { McpX402ToolDef } from "../types.js";
+export declare const x402DiscoverTool: McpX402ToolDef<typeof X402DiscoverSchema>;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/x402-discover/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/x402-discover/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAuDlD,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,OAAO,kBAAkB,CAStE,CAAC"}

package/dist/tools/x402-discover/index.js

@@ -0,0 +1,40 @@
+import { X402DiscoverSchema } from "./schema.js";
+const DEFAULT_FACILITATOR_BASE_URL = "https://ai.cryptoapis.io/x402/merchant";
+/**
+ * List x402-enabled resources from the facilitator's Bazaar catalogue.
+ *
+ * No credential is sent: `/discovery/resources` is public by design, so an agent can
+ * survey what is for sale — and at what price — before deciding whether to spend.
+ */
+async function x402Discover(input) {
+    const root = (input.facilitatorBaseUrl ?? DEFAULT_FACILITATOR_BASE_URL).replace(/\/$/, "");
+    const params = new URLSearchParams();
+    if (input.type !== undefined)
+        params.set("type", input.type);
+    if (input.limit !== undefined)
+        params.set("limit", String(input.limit));
+    if (input.offset !== undefined)
+        params.set("offset", String(input.offset));
+    const qs = params.toString();
+    const res = await fetch(`${root}/discovery/resources${qs ? `?${qs}` : ""}`, { method: "GET" });
+    if (!res.ok) {
+        // 503 here means the catalogue is unreadable, NOT that there is nothing for sale —
+        // surface the difference so the agent retries instead of concluding "no resources".
+        throw new Error(`x402 discovery failed: ${res.status} ${await res.text().catch(() => "")}`.trim());
+    }
+    const body = (await res.json());
+    return {
+        resources: body.items ?? [],
+        pagination: body.pagination ?? { limit: 0, offset: 0, total: 0 },
+    };
+}
+export const x402DiscoverTool = {
+    name: "x402_discover",
+    description: "Discover x402-gated APIs you can pay for — browse the facilitator's Bazaar catalogue of registered x402 resources, each with the price and payment terms it accepts. Use this BEFORE x402_pay whenever you need to FIND a paid endpoint rather than call one you were already given: the pay tool only fetches a URL you hand it, so this is the only way to locate a monetized API on your own. Returns { resources: [{ resource, type, x402Version, accepts: [{ scheme, network, amount, asset, payTo }], lastUpdated, metadata? }], pagination: { limit, offset, total } } — `amount` is in ATOMIC units (USDC 6-decimals: \"10000\" = $0.01), so convert before quoting a price to the user. PUBLIC: needs no API key, no wallet and spends nothing, so it is always safe to call. Filter with `type` (e.g. \"http\") and page with `limit`/`offset`. Then pass a chosen `resource` URL to x402_pay to actually buy it.",
+    inputSchema: X402DiscoverSchema,
+    handler: async (input) => {
+        const result = await x402Discover(input);
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/tools/x402-discover/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/x402-discover/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,4BAA4B,GAAG,wCAAwC,CAAC;AAoB9E;;;;;GAKG;AACH,KAAK,UAAU,YAAY,CAAC,KAAwB;IAIhD,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,kBAAkB,IAAI,4BAA4B,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3F,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7D,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3E,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAE7B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,uBAAuB,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/F,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACV,mFAAmF;QACnF,oFAAoF;QACpF,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,MAAM,IAAI,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IACvG,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAG7B,CAAC;IACF,OAAO;QACH,SAAS,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE;QAC3B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;KACnE,CAAC;AACN,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAA8C;IACvE,IAAI,EAAE,eAAe;IACrB,WAAW,EACP,63BAA63B;IACj4B,WAAW,EAAE,kBAAkB;IAC/B,OAAO,EAAE,KAAK,EAAE,KAAwB,EAAE,EAAE;QACxC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;IACzE,CAAC;CACJ,CAAC"}

package/dist/tools/x402-discover/schema.d.ts

@@ -0,0 +1,27 @@
+import * as z from "zod";
+/**
+ * Browse the x402 "Bazaar" — the catalogue of x402-enabled resources registered with a
+ * facilitator, each with the payment requirements it accepts (x402 v2 §8).
+ *
+ * This is the FIND half of x402: `x402_pay` can only pay a URL it is handed, so without
+ * discovery an agent can never locate a paid API on its own. The endpoint is PUBLIC — no
+ * API key and no wallet — so browsing costs nothing and commits nothing.
+ */
+export declare const X402DiscoverSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    facilitatorBaseUrl: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    facilitatorBaseUrl?: string | undefined;
+}, {
+    type?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    facilitatorBaseUrl?: string | undefined;
+}>;
+export type X402DiscoverInput = z.infer<typeof X402DiscoverSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/tools/x402-discover/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/tools/x402-discover/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;EAuB7B,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/tools/x402-discover/schema.js

@@ -0,0 +1,34 @@
+import * as z from "zod";
+/**
+ * Browse the x402 "Bazaar" — the catalogue of x402-enabled resources registered with a
+ * facilitator, each with the payment requirements it accepts (x402 v2 §8).
+ *
+ * This is the FIND half of x402: `x402_pay` can only pay a URL it is handed, so without
+ * discovery an agent can never locate a paid API on its own. The endpoint is PUBLIC — no
+ * API key and no wallet — so browsing costs nothing and commits nothing.
+ */
+export const X402DiscoverSchema = z.object({
+    type: z
+        .string()
+        .optional()
+        .describe('Filter by resource type, e.g. "http". Omit to list every type.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Max results to return, 1-100 (default 20). The facilitator clamps out-of-range values rather than erroring."),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("How many results to skip, for paging (default 0). Use with `pagination.total` from a previous call."),
+    facilitatorBaseUrl: z
+        .string()
+        .url()
+        .optional()
+        .describe("Override the facilitator base URL (default https://ai.cryptoapis.io/x402/merchant). Useful against QA/local."),
+});
+//# sourceMappingURL=schema.js.map

package/dist/tools/x402-discover/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/tools/x402-discover/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC;SACF,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,gEAAgE,CAAC;IAC/E,KAAK,EAAE,CAAC;SACH,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,6GAA6G,CAAC;IAC5H,MAAM,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,qGAAqG,CAAC;IACpH,kBAAkB,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,CAAC,8GAA8G,CAAC;CAChI,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cryptoapis-io/mcp-x402-pay",
   "mcpName": "io.github.CryptoAPIs-io/mcp-x402-pay",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "MCP server that pays x402-gated HTTP endpoints — one x402_pay tool that fetches, and on a 402 authorizes via the CryptoAPIs buyer service, signs LOCALLY, and retries.",
   "license": "MIT",
   "type": "module",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/CryptoAPIs-io/cryptoapis-mcp-x402-pay",
     "source": "github"
   },
-  "version": "0.1.2",
+  "version": "0.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@cryptoapis-io/mcp-x402-pay",
-      "version": "0.1.2",
+      "version": "0.2.0",
       "transport": {
         "type": "stdio"
       }