agent402-mcp 0.14.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,7 +11,7 @@ Pick one setup. Both run locally through `npx`.
11
11
  **1. Free, no wallet.** Pure-CPU tools (no outbound calls, keys or models) run free. Each call solves a proof-of-work puzzle with your CPU, typically well under a second on a laptop. Tools that reach the network or a model ask for a wallet.
12
12
 
13
13
  ```
14
- claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.1
14
+ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.15.0
15
15
  ```
16
16
 
17
17
  **2. Paid, with a wallet.** Paid tools are settled in USDC on each call.
@@ -21,7 +21,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.1
21
21
  "mcpServers": {
22
22
  "agent402": {
23
23
  "command": "npx",
24
- "args": ["-y", "agent402-mcp@0.14.1"],
24
+ "args": ["-y", "agent402-mcp@0.15.0"],
25
25
  "env": { "AGENT_KEY": "0xYOUR_PRIVATE_KEY" }
26
26
  }
27
27
  }
@@ -32,7 +32,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.1
32
32
 
33
33
  Use `SOLANA_AGENT_KEY` instead for USDC on Solana. Each call is capped at $5 by default to protect your wallet (`AGENT402_MAX_PER_CALL`, `0` or `off` turns it off); there is no session budget unless you set `AGENT402_BUDGET`.
34
34
 
35
- Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.14.1`
35
+ Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.15.0`
36
36
  (use a new wallet holding only a few dollars of USDC; never your main wallet).
37
37
 
38
38
  Advanced setup (chains, MPP, error codes, the hosted connector) is in [Advanced](#advanced).
@@ -83,7 +83,10 @@ seller that kept the authorization could still redeem it, so it counts against
83
83
  (`https://agent402.tools`, matched by exact origin), an error status is never
84
84
  settled, so a hold for one ends at the authorization's `validBefore` plus 10
85
85
  minutes (15 minutes after the answer when no `validBefore` is readable). A held
86
- amount whose authorization expires unused is released, never charged. A payment
86
+ amount whose authorization expires unused is released, never charged. Some calls are paid before they run; a failed one can be retried free with the same payment, or is refunded. A
87
+ failure whose body says `charged: true` and `retry: "same-payment"` is that case:
88
+ this server sends the same payment once more, as it was signed, and counts the
89
+ amount once against `AGENT402_BUDGET` as spent, never held. A payment
87
90
  option asking to stay valid for more than a day is refused before anything is
88
91
  signed, so no signed authorization outlives a day.
89
92
 
@@ -96,7 +99,7 @@ its variable name, not its value.
96
99
 
97
100
  **Hosted connector (no install).** Add `https://agent402.tools/mcp` as a remote MCP server (for example claude.ai → Settings → Connectors → Add custom connector). Pure-CPU tools run free there, rate-limited. Paid tools are payable on the connector over [MPP](https://agent402.tools/what-is-mpp): the connector answers with an `isError` tool result whose text names every way to pay and whose `_meta["org.paymentauth/payment-required"]` carries the challenges. A presented credential that is refused answers JSON-RPC `-32043`, and a call on the tasks path answers `-32042`, both with `data.challenges`. An MCP client wrapped with `mppx`'s `McpClient.wrap()` pays and retries on its own, with the receipt in `_meta`. This package runs locally for no rate limit, or to pay over x402.
98
101
 
99
- **Chains.** With a funded wallet, `AGENT_KEY` pays USDC on any EVM chain the server offers (Base, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Arc, Ink) or USDG on Robinhood Chain. `SOLANA_AGENT_KEY` pays USDC on Solana. The service also settles on Stellar and Algorand, which this package does not sign. Restrict or order chains with `AGENT402_NETWORKS`.
102
+ **Chains.** With a funded wallet, `AGENT_KEY` pays USDC on any EVM chain the server offers (Base, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Arc, Ink) or USDG on Robinhood Chain. `SOLANA_AGENT_KEY` pays USDC on Solana. The service also settles on Stellar and Algorand, which this package does not sign. Restrict or order chains with `AGENT402_NETWORKS`. A paid call names the `AGENT_KEY` wallet in the `X-Agent402-Wallet` request header with a fresh `X-Agent402-Wallet-Proof` (that key's signature for the host and route), so a server that prices a returning wallet lower can quote it on that call; free calls never carry them.
100
103
 
101
104
  **Credits key.** A prepaid credits key (`AGENT402_CREDITS_KEY`) pays per successful call on Agent402's own services; the routes that buy from outside sellers (`router.execute`, `seller-payability`, `decide.execute`, the flight tools) need a wallet key. [agent402.tools/credits](https://agent402.tools/credits) says whether packs are on sale.
102
105
 
@@ -125,6 +128,7 @@ its variable name, not its value.
125
128
  | --- | --- | --- |
126
129
  | ≤ $0.005 | $0.01 | `POST /api/route/execute` |
127
130
  | ≤ $0.04 | $0.05 | `POST /api/route/execute-plus` |
131
+ | ≤ $0.10 | $0.12 | `POST /api/route/execute-mid` |
128
132
  | ≤ $0.50 | $0.55 | `POST /api/route/execute-max` |
129
133
 
130
134
  A tool priced above the tier's ceiling returns a self-correcting 409 naming its direct route.
package/index.js CHANGED
@@ -311,7 +311,9 @@ function getPayFetch() {
311
311
  });
312
312
  // Registered after the guard's check of the signed amount, so it runs only
313
313
  // for a payload about to be sent: from here the payment is outstanding.
314
- client.onAfterPaymentCreation(async ({ paymentPayload } = {}) => { const e = signCtx.getStore(); if (e && e.signed) { e.sent = true; e.until = signedValidUntilMs(paymentPayload); } });
314
+ // The payload is kept, so a payment the seller took before a run that
315
+ // failed can be sent once more as it was (never signed again).
316
+ client.onAfterPaymentCreation(async ({ paymentPayload } = {}) => { const e = signCtx.getStore(); if (e && e.signed) { e.sent = true; e.until = signedValidUntilMs(paymentPayload); e.payload = paymentPayload || null; } });
315
317
  if (AGENT_KEY) {
316
318
  const { registerExactEvmScheme } = await import("@x402/evm/exact/client");
317
319
  const { privateKeyToAccount } = await import("viem/accounts");
@@ -332,6 +334,37 @@ function getPayFetch() {
332
334
  return payFetchPromise;
333
335
  }
334
336
 
337
+ // The EVM wallet AGENT_KEY pays from, named on every paid call in the
338
+ // X-Agent402-Wallet header with a fresh proof that this key holds it
339
+ // (X-Agent402-Wallet-Proof: unix seconds and the key's EIP-191 signature over
340
+ // the server's host name, the route, the wallet and those seconds), so a
341
+ // server that prices a returning wallet lower can quote it on that call. The
342
+ // signed retry resends both. Null without an EVM key or when the key is
343
+ // malformed (the paid path reports that itself); never sent on a free call.
344
+ let walletHintPromise = null;
345
+ function walletHint() {
346
+ walletHintPromise ??= (async () => {
347
+ if (!AGENT_KEY) return null;
348
+ try { const { privateKeyToAccount } = await import("viem/accounts"); return evmAccount(privateKeyToAccount); } catch { return null; }
349
+ })();
350
+ return walletHintPromise;
351
+ }
352
+ /** The text the wallet signs for one host and route at `time` (unix seconds). */
353
+ function walletProofMessage({ host, route, wallet, time }) {
354
+ return `Agent402 returning-wallet price\nhost: ${String(host).toLowerCase()}\nroute: ${route}\nwallet: ${String(wallet).toLowerCase()}\ntime: ${time}`;
355
+ }
356
+ /** The headers a paid call to `tool` adds for its wallet hint and proof ({} when there is none). */
357
+ async function walletHintHeaders(tool) {
358
+ const account = await walletHint();
359
+ if (!account) return {};
360
+ try {
361
+ const time = String(Math.floor(Date.now() / 1000));
362
+ const route = `${String(tool.method || "POST").toUpperCase()} ${tool.path}`;
363
+ const signature = await account.signMessage({ message: walletProofMessage({ host: new URL(BASE).hostname, route, wallet: account.address, time }) });
364
+ return { "X-Agent402-Wallet": account.address, "X-Agent402-Wallet-Proof": `${time}.${signature}` };
365
+ } catch { return {}; }
366
+ }
367
+
335
368
  /** The viem account for AGENT_KEY, or walletKeyError. */
336
369
  function evmAccount(privateKeyToAccount) {
337
370
  try { return privateKeyToAccount(AGENT_KEY.trim()); } catch { throw walletKeyError("AGENT_KEY", "a 0x-prefixed 32-byte hex private key"); }
@@ -431,6 +464,23 @@ async function quotedUsd(url, init, listUsd) {
431
464
  // an agent cannot act on in text. Keep the refusal's own fields (error,
432
465
  // reason, hint, retry) and say where the offer is; any other body is returned
433
466
  // as it came.
467
+ /** True when a failed paid answer says its payment was settled before the
468
+ * call ran (charged: true, retry: "same-payment"). Read from a copy. */
469
+ async function settledFirstFailure(res) {
470
+ try {
471
+ const body = typeof res?.clone === "function" ? await res.clone().json() : null;
472
+ return !!body && typeof body === "object" && body.charged === true && body.retry === "same-payment";
473
+ } catch { return false; }
474
+ }
475
+ /** The payment header that carries `payload` as it was signed, or null. */
476
+ async function paymentHeaderFor(payload) {
477
+ if (!payload || typeof payload !== "object") return null;
478
+ try {
479
+ const { encodePaymentSignatureHeader } = await import("@x402/core/http");
480
+ return { "PAYMENT-SIGNATURE": encodePaymentSignatureHeader(payload) };
481
+ } catch { return null; }
482
+ }
483
+
434
484
  function failureText(status, text) {
435
485
  let doc;
436
486
  try { doc = JSON.parse(text); } catch { return text; }
@@ -548,10 +598,12 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
548
598
  const payFetch = await getPayFetch();
549
599
  // Held until the call settles or fails; the guard replaces `usd` with the
550
600
  // amount it lets the wallet sign.
551
- const entry = { usd: price, signed: false, sent: false, refusal: null };
601
+ const entry = { usd: price, signed: false, sent: false, refusal: null, payload: null };
552
602
  pendingSpend.add(entry);
603
+ let hintHeaders = {};
553
604
  try {
554
- const first = await signCtx.run(entry, () => payFetch(url, { ...paidInit, headers: { ...init.headers, ...asyncHeaders } }));
605
+ hintHeaders = await walletHintHeaders(tool);
606
+ const first = await signCtx.run(entry, () => payFetch(url, { ...paidInit, headers: { ...init.headers, ...asyncHeaders, ...hintHeaders } }));
555
607
  if (isRedirect(first)) {
556
608
  pendingSpend.delete(entry);
557
609
  // A signature already sent leaves that payment's outcome unknown, so
@@ -571,10 +623,27 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
571
623
  throw e;
572
624
  }
573
625
  pendingSpend.delete(entry);
626
+ // A payment the seller settled BEFORE the call ran, whose run then
627
+ // failed (the body says charged: true and retry: "same-payment"): the
628
+ // same payment is sent once more, as it was signed, and the seller runs
629
+ // it at no further charge. Its amount counts once, as spent.
630
+ let takenFirst = false, resent = false;
631
+ if (entry.sent && res.status >= 400 && await settledFirstFailure(res)) {
632
+ takenFirst = true;
633
+ const header = await paymentHeaderFor(entry.payload);
634
+ if (header) {
635
+ resent = true;
636
+ try { res = await collect(await ownFetch(url, { ...paidInit, headers: { ...init.headers, ...asyncHeaders, ...hintHeaders, ...header } })); }
637
+ catch (e) { spentUsd += entry.usd; if (e instanceof AsyncJobPendingError) return pendingJobResult(tool, e); throw e; }
638
+ }
639
+ }
574
640
  // A sent payment is spent when the server confirms settlement (payment
575
641
  // receipt header) or answers 2xx; any other answer leaves the signed
576
642
  // authorization with the seller, so it is held, never released.
577
- if (entry.sent) {
643
+ if (entry.sent && takenFirst) {
644
+ spentUsd += entry.usd;
645
+ if (!res.ok) heldNote = ` The payment of $${entry.usd} was taken before the call ran, so it counts as spent against AGENT402_BUDGET and is owed back, refunded after on-chain proof${resent ? "; the same payment, sent once more, failed too" : "; sending the same payment again runs the call at no further charge"}.`;
646
+ } else if (entry.sent) {
578
647
  if (res.headers.get("payment-response") || res.headers.get("x-payment-response") || res.ok) spentUsd += entry.usd;
579
648
  else if (res.status >= 400 && url.origin === DEFAULT_ORIGIN) {
580
649
  // The default host did not settle it: held until it expires unused.
@@ -977,7 +1046,7 @@ server.setRequestHandler("tools/list", redacted(withCatalog(async () => {
977
1046
  properties: {
978
1047
  task: { type: "string", description: "Plain-language task, e.g. 'crypto news headlines' or 'sentiment of a tweet'. Resolved to a proven external seller." },
979
1048
  params: { type: ["object", "string"], description: "Input parameters for the resolved external tool (optional; the seller decides its own schema): an object, or a JSON string of one." },
980
- maxUsd: { type: "number", description: "Max underlying seller price in USD. Default 0.005 (the $0.01 fee tier); above 0.005 and up to 0.04 uses the $0.05 tier; above 0.04 the $0.55 tier (seller up to $0.50)." },
1049
+ maxUsd: { type: "number", description: "Max underlying seller price in USD. Default 0.005 (the $0.01 fee tier); above 0.005 and up to 0.04 uses the $0.05 tier; above 0.04 and up to 0.10 the $0.12 tier; above 0.10 the $0.55 tier (seller up to $0.50)." },
981
1050
  },
982
1051
  required: ["task"],
983
1052
  },
@@ -1093,7 +1162,7 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
1093
1162
  claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
1094
1163
  claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
1095
1164
  cursorHosted: { mcpServers: { agent402: { url: `${BASE}/mcp` } } },
1096
- npm: "npx -y agent402-mcp@0.14.1",
1165
+ npm: "npx -y agent402-mcp@0.15.0",
1097
1166
  maintainer: "Havok Holdings LLC",
1098
1167
  },
1099
1168
  positioning: `Agent402 is the payment and trust layer for agent commerce: agents find, pay for and verify every paid call to Agent402, across x402 and MPP, with a signed receipt for each one. 500+ ready tools on the same rails. Flagship search/answer first, the long tail via catalog.find / catalog.search / catalog.call. Agent402 is the applied layer of Agentic Finance: agents that pay and get paid per request over x402 or MPP (Machine Payments Protocol), both on the same 402 - ${BASE}/agentic-finance, ${BASE}/glossary.`,
@@ -1113,7 +1182,7 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
1113
1182
  install: {
1114
1183
  claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
1115
1184
  claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
1116
- npm: "npx -y agent402-mcp@0.14.1",
1185
+ npm: "npx -y agent402-mcp@0.15.0",
1117
1186
  maintainer: "Havok Holdings LLC",
1118
1187
  },
1119
1188
  tools: catalog.size,
@@ -1218,12 +1287,17 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
1218
1287
  if (!task) return { content: [{ type: "text", text: "router.execute requires a 'task' (plain-language description of what you need)." }], isError: true };
1219
1288
  const maxUsd = Number(args.maxUsd) > 0 ? Number(args.maxUsd) : 0.005;
1220
1289
  // Pick the CHEAPEST tier whose underlying cap covers maxUsd. The ladder
1221
- // has three rungs; skipping the middle one billed 11x for a mid-priced
1222
- // seller (a $0.02 seller went through the $0.55 tier instead of $0.05).
1290
+ // skipped a middle rung once and billed 11x for a mid-priced seller (a
1291
+ // $0.02 seller went through the $0.55 tier instead of $0.05).
1223
1292
  // Keep this ordered cheapest-first so a new rung is a one-line insert.
1224
- const slug = maxUsd > 0.04 ? "route-execute-max"
1225
- : maxUsd > 0.005 ? "route-execute-plus"
1226
- : "route-execute";
1293
+ // A server that does not list a rung yet is served by the next one up.
1294
+ const ROUTER_TIERS = [
1295
+ { slug: "route-execute", underlyingMaxUsd: 0.005 },
1296
+ { slug: "route-execute-plus", underlyingMaxUsd: 0.04 },
1297
+ { slug: "route-execute-mid", underlyingMaxUsd: 0.1 },
1298
+ { slug: "route-execute-max", underlyingMaxUsd: 0.5 },
1299
+ ];
1300
+ const slug = ROUTER_TIERS.find((t) => maxUsd <= t.underlyingMaxUsd && catalog.has(t.slug))?.slug || "route-execute-max";
1227
1301
  const tool = catalog.get(slug);
1228
1302
  if (!tool) return { content: [{ type: "text", text: `External routing (${slug}) is not in the catalog from ${BASE} yet. It may be rolling out; retry shortly.` }], isError: true };
1229
1303
  // Body matches the route-execute input schema; include:"external" is what
package/output-schemas.js CHANGED
@@ -494,7 +494,7 @@ export function mcpJsonResult(obj) {
494
494
  * Hosted URL is parameterized; npm / Claude Code / Cursor notes
495
495
  * match docs/ecosystem-listings.md + wiki/MCP-Connector.md.
496
496
  */
497
- export const AGENT402_MCP_VERSION = "0.14.1";
497
+ export const AGENT402_MCP_VERSION = "0.15.0";
498
498
 
499
499
  /** A listed MCP tool description, at most `max` characters. Hosts truncate or
500
500
  * skip long descriptions, so the listing keeps the first whole sentences; the
@@ -526,12 +526,12 @@ export function mcpInstallHints(baseUrl) {
526
526
  mcpServers: {
527
527
  agent402: {
528
528
  command: "npx",
529
- args: ["-y", "agent402-mcp@0.14.1"],
529
+ args: ["-y", "agent402-mcp@0.15.0"],
530
530
  env: { AGENT_KEY: "0xYOUR_PRIVATE_KEY" },
531
531
  },
532
532
  },
533
533
  },
534
- npm: "npx -y agent402-mcp@0.14.1",
534
+ npm: "npx -y agent402-mcp@0.15.0",
535
535
  maintainer: "Havok Holdings LLC",
536
536
  };
537
537
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent402-mcp",
3
- "version": "0.14.1",
3
+ "version": "0.15.0",
4
4
  "mcpName": "io.github.MikeyPetrillo/agent402",
5
5
  "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
6
6
  "homepage": "https://agent402.tools",