Merge pull request #433 from basementstudio/canary

v0.5.8

Author: valebearzotti

examples/x402-http/.env.example

@@ -0,0 +1,5 @@
+# Wallet address to receive USDC payments
+X402_WALLET=0xYOUR_WALLET_ADDRESS_HERE
+
+# Optional: Custom facilitator URL (defaults to https://x402.org/facilitator)
+# X402_FACILITATOR=https://x402.org/facilitator

examples/x402-http/.gitignore

@@ -0,0 +1,4 @@
+.vercel
+.xmcp
+xmcp-env.d.ts
+.env

examples/x402-http/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "paid-http-transport",
+  "description": "Example of x402 paid tools with xmcp HTTP transport",
+  "keywords": [
+    "http",
+    "x402",
+    "paid"
+  ],
+  "scripts": {
+    "build": "xmcp build",
+    "dev": "xmcp dev",
+    "start": "node dist/http.js"
+  },
+  "dependencies": {
+    "@xmcp-dev/x402": "workspace:*",
+    "xmcp": "workspace:*",
+    "zod": "^4.0.10"
+  }
+}

examples/x402-http/src/middleware.ts

@@ -0,0 +1,12 @@
+import { x402Provider } from "@xmcp-dev/x402";
+
+export default x402Provider({
+  wallet: process.env.X402_WALLET!,
+  facilitator: process.env.X402_FACILITATOR ?? "https://x402.org/facilitator",
+  debug: true,
+  defaults: {
+    price: 0.01,
+    currency: "USDC",
+    network: "base-sepolia",
+  },
+});

examples/x402-http/src/tools/greet.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { type InferSchema, type ToolMetadata } from "xmcp";
+import { paid } from "@xmcp-dev/x402";
+
+// Define the schema for tool parameters
+export const schema = {
+  name: z.string().describe("The name of the user to greet"),
+};
+
+// Define tool metadata
+export const metadata: ToolMetadata = {
+  name: "greet",
+  description: "Greet the user (paid tool - $0.01)",
+  annotations: {
+    title: "Greet the user",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+  },
+};
+
+// Paid tool implementation - uses middleware defaults ($0.01)
+export default paid(async function greet({ name }: InferSchema<typeof schema>) {
+  return `Hello, ${name}!! (paid by fran)`;
+});

examples/x402-http/src/tools/hash-string.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { type InferSchema, type ToolMetadata } from "xmcp";
+import { paid } from "@xmcp-dev/x402";
+
+export const schema = {
+  input: z
+    .string()
+    .min(1, "Input string is required")
+    .describe("The string to hash"),
+};
+
+export const metadata: ToolMetadata = {
+  name: "hash-string",
+  description: "Hash a string using SHA-256 (paid tool - $0.05)",
+};
+
+// Paid tool with custom price
+export default paid(
+  { price: 0.05 },
+  async function hashString({ input }: InferSchema<typeof schema>) {
+    if (!input || typeof input !== "string")
+      return "Invalid input: string required";
+
+    // Use Web Crypto API for SHA-256 hashing
+    async function sha256(str: string) {
+      const encoder = new TextEncoder();
+      const data = encoder.encode(str);
+      const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+      const hashArray = Array.from(new Uint8Array(hashBuffer));
+      return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    }
+
+    const hash = await sha256(input);
+
+    return hash;
+  }
+);

examples/x402-http/src/tools/random-number.ts

@@ -0,0 +1,12 @@
+import { ToolMetadata } from "xmcp";
+
+export const metadata: ToolMetadata = {
+  name: "random-number",
+  description: "Generate a random number (free tool)",
+};
+
+export default async function randomNumber() {
+  const result = Math.random();
+
+  return result.toString();
+}

examples/x402-http/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "es2017",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["xmcp-env.d.ts", "src/**/*.ts"]
+}

examples/x402-http/xmcp.config.ts

@@ -0,0 +1,11 @@
+import { XmcpConfig } from "xmcp";
+
+const config: XmcpConfig = {
+  http: true,
+  paths: {
+    prompts: false,
+    resources: false,
+  },
+};
+
+export default config;

packages/plugins/x402/README.md

@@ -0,0 +1,111 @@
+# @xmcp-dev/x402
+
+x402 payment protocol plugin for xmcp. Add paid tools with USDC on Base.
+
+## Installation
+
+```bash
+pnpm add @xmcp-dev/x402
+```
+
+## Usage
+
+### Middleware
+
+```typescript
+// src/middleware.ts
+import { x402Middleware } from "@xmcp-dev/x402";
+
+export default x402Middleware({
+  wallet: process.env.X402_WALLET!,
+  defaults: {
+    price: 0.01,
+    network: "base-sepolia",
+  },
+});
+```
+
+### Paid tools
+
+```typescript
+// src/tools/my-tool.ts
+import { paid } from "@xmcp-dev/x402";
+
+export default paid(async ({ input }) => {
+  return { content: [{ type: "text", text: `Result: ${input}` }] };
+});
+```
+
+```typescript
+// src/tools/premium-tool.ts
+import { paid } from "@xmcp-dev/x402";
+
+export default paid({ price: 0.10 }, async ({ input }) => {
+  return { content: [{ type: "text", text: `Premium: ${input}` }] };
+});
+```
+
+### Payment context
+
+```typescript
+import { paid, payment } from "@xmcp-dev/x402";
+
+export default paid(async ({ input }) => {
+  const { payer, amount, network } = payment();
+  return { content: [{ type: "text", text: `Paid by ${payer}` }] };
+});
+```
+
+## API
+
+### `x402Middleware(config)`
+
+```typescript
+interface X402Config {
+  wallet: string;
+  facilitator?: string;
+  debug?: boolean;
+  defaults?: {
+    price?: number;
+    currency?: string;
+    network?: string;
+    maxPaymentAge?: number;
+  };
+}
+```
+
+### `paid(options?, handler)`
+
+```typescript
+interface X402ToolOptions {
+  price?: number;
+  currency?: string;
+  network?: string;
+  maxPaymentAge?: number;
+  description?: string;
+}
+```
+
+### `payment()`
+
+```typescript
+interface X402PaymentContext {
+  payer: string;
+  amount: string;
+  network: string;
+  asset: string;
+  toolName: string;
+  transactionHash?: string;
+}
+```
+
+## Networks
+
+| Network | USDC Address |
+|---------|--------------|
+| `base` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+| `base-sepolia` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
+
+## License
+
+MIT