@agentcash/router 1.1.4 → 1.1.6

package/.claude/skills/router-guide/SKILL.md

@@ -368,6 +368,8 @@ for (const entry of router.monitors()) {
 
 ## Discovery Setup
 
+Discovery metadata (`title`, `version`, `description`, `guidance`) is configured once in `createRouter({ discovery })`. The discovery handlers are zero-arg:
+
 ```typescript
 // app/.well-known/x402/route.ts
 import '@/lib/routes/barrel';  // barrel import FIRST to register all routes
@@ -377,7 +379,11 @@ export const GET = router.wellKnown();
 // app/openapi.json/route.ts
 import '@/lib/routes/barrel';
 import { router } from '@/lib/routes';
-export const GET = router.openapi({ title: 'My API', version: '1.0.0' });
+export const GET = router.openapi();
+
+// app/llms.txt/route.ts
+import { router } from '@/lib/routes';
+export const GET = router.llmsTxt();
 ```
 
 **Barrel import must come first.** Without it, Next.js lazy-loads route modules, so discovery endpoints hit before routes register → `route 'X' in prices map but not registered` error.

package/README.md

@@ -60,6 +60,11 @@ export const router = createRouter({
   payeeAddress: process.env.X402_PAYEE_ADDRESS!,
   baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
   strictRoutes: true, // recommended
+  discovery: {
+    title: 'My API',
+    version: '1.0.0',
+    description: 'Pay-per-call API',
+  },
 });
 ```
 
@@ -99,28 +104,29 @@ export const GET = router.route({ path: 'health' })
 
 ### 3. Auto-discovery
 
+Discovery metadata (`title`, `version`, `description`, `guidance`) is configured once in `createRouter({ discovery })`. The discovery handlers are zero-arg:
+
 ```typescript
 // app/.well-known/x402/route.ts
 import { router } from '@/lib/routes';
 import '@/lib/routes/barrel'; // ensures all routes are imported
-export const GET = router.wellKnown({ methodHints: 'non-default' });
+export const GET = router.wellKnown();
 
 // app/openapi.json/route.ts
 import { router } from '@/lib/routes';
 import '@/lib/routes/barrel';
-export const GET = router.openapi({
-  title: 'My API',
-  version: '1.0.0',
-  llmsTxtUrl: 'https://my-api.dev/llms.txt',
-  ownershipProofs: ['did:example:proof'],
-});
+export const GET = router.openapi();
+
+// app/llms.txt/route.ts
+import { router } from '@/lib/routes';
+export const GET = router.llmsTxt();
 ```
 
 OpenAPI output follows the discovery contract:
 
 - Paid signaling via `responses.402` + `x-payment-info`
 - Auth signaling via `security` + `components.securitySchemes`
-- Optional top-level metadata via `x-discovery` (`llmsTxtUrl`, `ownershipProofs`)
+- Optional top-level metadata via `x-discovery` (`ownershipProofs`)
 
 ## API
 
@@ -130,8 +136,9 @@ Creates a `ServiceRouter` instance.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `payeeAddress` | `string` | **required** | Wallet address to receive payments |
+| `payeeAddress` | `string` | — | Wallet address to receive payments |
 | `baseUrl` | `string` | **required** | Service origin used for discovery/OpenAPI/realm |
+| `discovery` | `DiscoveryConfig` | **required** | Title, version, description, guidance for OpenAPI/well-known/llms.txt |
 | `network` | `string` | `'eip155:8453'` | Blockchain network |
 | `plugin` | `RouterPlugin` | `undefined` | Observability plugin |
 | `prices` | `Record<string, string>` | `undefined` | Central pricing map (auto-applied) |

package/dist/index.cjs

@@ -1108,7 +1108,7 @@ function createRequestHandler(routeEntry, handler, deps) {
         }
         const response = new import_server2.NextResponse(JSON.stringify(paymentRequired), {
           status: 402,
-          headers: { "Content-Type": "application/json" }
+          headers: { "Content-Type": "application/json", "Cache-Control": "no-store" }
         });
         if (encoded) response.headers.set("PAYMENT-REQUIRED", encoded);
         firePluginResponse(deps, pluginCtx, meta, response);
@@ -1269,6 +1269,7 @@ function createRequestHandler(routeEntry, handler, deps) {
             }
           }
           response.headers.set("PAYMENT-RESPONSE", settle.encoded);
+          response.headers.set("Cache-Control", "private");
           firePluginHook(deps.plugin, "onPaymentSettled", pluginCtx, {
             protocol: "x402",
             payer: verify.payer,
@@ -1359,6 +1360,7 @@ function createRequestHandler(routeEntry, handler, deps) {
           }
         }
         const receiptResponse = mppResult.withReceipt(response);
+        receiptResponse.headers.set("Cache-Control", "private");
         finalize(receiptResponse, rawResult, meta, pluginCtx, body.data);
         return receiptResponse;
       }
@@ -1447,7 +1449,8 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
   const response = new import_server2.NextResponse(null, {
     status: 402,
     headers: {
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
     }
   });
   let challengePrice;
@@ -2233,16 +2236,23 @@ function createRouter(config) {
       try {
         const { Mppx, tempo } = await import("mppx/server");
         const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL;
+        const getClient = async () => {
+          const { createClient, http } = await import("viem");
+          const { tempo: tempoChain } = await import("viem/chains");
+          return createClient({ chain: tempoChain, transport: http(rpcUrl) });
+        };
+        let feePayerAccount;
+        if (config.mpp.feePayerKey) {
+          const { privateKeyToAccount } = await import("viem/accounts");
+          feePayerAccount = privateKeyToAccount(config.mpp.feePayerKey);
+        }
         deps.mppx = Mppx.create({
           methods: [
             tempo.charge({
               currency: config.mpp.currency,
               recipient: config.mpp.recipient ?? config.payeeAddress,
-              getClient: async () => {
-                const { createClient, http } = await import("viem");
-                const { tempo: tempoChain } = await import("viem/chains");
-                return createClient({ chain: tempoChain, transport: http(rpcUrl) });
-              }
+              getClient,
+              ...feePayerAccount ? { feePayer: feePayerAccount } : {}
             })
           ],
           secretKey: config.mpp.secretKey,
@@ -2274,12 +2284,14 @@ function createRouter(config) {
       }
       let builder = new RouteBuilder(key, registry, deps);
       builder = builder.path(normalizedPath);
+      if (config.protocols) {
+        builder._protocols = [...config.protocols];
+      }
       if (definition.method) {
         builder = builder.method(definition.method);
       }
       if (config.prices && key in config.prices) {
-        const options = config.protocols ? { protocols: config.protocols } : void 0;
-        return builder.paid(config.prices[key], options);
+        return builder.paid(config.prices[key]);
       }
       return builder;
     },

package/dist/index.d.cts

@@ -347,6 +347,12 @@ interface RouterConfig {
         recipient?: string;
         /** Tempo RPC URL for on-chain verification. Falls back to TEMPO_RPC_URL env var. */
         rpcUrl?: string;
+        /**
+         * Private key of the account that sponsors transaction fees.
+         * When set, clients don't need gas tokens — the server pays fees on their behalf.
+         * Must be a hex-encoded private key (e.g. `0xabc123...`).
+         */
+        feePayerKey?: string;
     };
     /**
      * Payment protocols to accept on auto-priced routes (those using the `prices` config).

package/dist/index.d.ts

@@ -347,6 +347,12 @@ interface RouterConfig {
         recipient?: string;
         /** Tempo RPC URL for on-chain verification. Falls back to TEMPO_RPC_URL env var. */
         rpcUrl?: string;
+        /**
+         * Private key of the account that sponsors transaction fees.
+         * When set, clients don't need gas tokens — the server pays fees on their behalf.
+         * Must be a hex-encoded private key (e.g. `0xabc123...`).
+         */
+        feePayerKey?: string;
     };
     /**
      * Payment protocols to accept on auto-priced routes (those using the `prices` config).

package/dist/index.js

@@ -1069,7 +1069,7 @@ function createRequestHandler(routeEntry, handler, deps) {
         }
         const response = new NextResponse2(JSON.stringify(paymentRequired), {
           status: 402,
-          headers: { "Content-Type": "application/json" }
+          headers: { "Content-Type": "application/json", "Cache-Control": "no-store" }
         });
         if (encoded) response.headers.set("PAYMENT-REQUIRED", encoded);
         firePluginResponse(deps, pluginCtx, meta, response);
@@ -1230,6 +1230,7 @@ function createRequestHandler(routeEntry, handler, deps) {
             }
           }
           response.headers.set("PAYMENT-RESPONSE", settle.encoded);
+          response.headers.set("Cache-Control", "private");
           firePluginHook(deps.plugin, "onPaymentSettled", pluginCtx, {
             protocol: "x402",
             payer: verify.payer,
@@ -1320,6 +1321,7 @@ function createRequestHandler(routeEntry, handler, deps) {
           }
         }
         const receiptResponse = mppResult.withReceipt(response);
+        receiptResponse.headers.set("Cache-Control", "private");
         finalize(receiptResponse, rawResult, meta, pluginCtx, body.data);
         return receiptResponse;
       }
@@ -1408,7 +1410,8 @@ async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
   const response = new NextResponse2(null, {
     status: 402,
     headers: {
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
     }
   });
   let challengePrice;
@@ -2194,16 +2197,23 @@ function createRouter(config) {
       try {
         const { Mppx, tempo } = await import("mppx/server");
         const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL;
+        const getClient = async () => {
+          const { createClient, http } = await import("viem");
+          const { tempo: tempoChain } = await import("viem/chains");
+          return createClient({ chain: tempoChain, transport: http(rpcUrl) });
+        };
+        let feePayerAccount;
+        if (config.mpp.feePayerKey) {
+          const { privateKeyToAccount } = await import("viem/accounts");
+          feePayerAccount = privateKeyToAccount(config.mpp.feePayerKey);
+        }
         deps.mppx = Mppx.create({
           methods: [
             tempo.charge({
               currency: config.mpp.currency,
               recipient: config.mpp.recipient ?? config.payeeAddress,
-              getClient: async () => {
-                const { createClient, http } = await import("viem");
-                const { tempo: tempoChain } = await import("viem/chains");
-                return createClient({ chain: tempoChain, transport: http(rpcUrl) });
-              }
+              getClient,
+              ...feePayerAccount ? { feePayer: feePayerAccount } : {}
             })
           ],
           secretKey: config.mpp.secretKey,
@@ -2235,12 +2245,14 @@ function createRouter(config) {
       }
       let builder = new RouteBuilder(key, registry, deps);
       builder = builder.path(normalizedPath);
+      if (config.protocols) {
+        builder._protocols = [...config.protocols];
+      }
       if (definition.method) {
         builder = builder.method(definition.method);
       }
       if (config.prices && key in config.prices) {
-        const options = config.protocols ? { protocols: config.protocols } : void 0;
-        return builder.paid(config.prices[key], options);
+        return builder.paid(config.prices[key]);
       }
       return builder;
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -29,7 +29,7 @@
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
     "@x402/svm": "2.3.0",
-    "mppx": "^0.3.2",
+    "mppx": "^0.4.2",
     "next": ">=15.0.0",
     "zod": "^4.0.0",
     "zod-openapi": "^5.0.0"
@@ -61,7 +61,7 @@
     "@x402/extensions": "^2.3.0",
     "@x402/svm": "2.3.0",
     "eslint": "^10.0.0",
-    "mppx": "^0.4.1",
+    "mppx": "^0.4.2",
     "next": "^15.0.0",
     "prettier": "^3.8.1",
     "react": "^19.0.0",