agent402-mcp 0.13.22 → 0.13.25

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
@@ -9,7 +9,7 @@ Pick one setup. Both run locally through `npx`.
9
9
  **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.
10
10
 
11
11
  ```
12
- claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.22
12
+ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.25
13
13
  ```
14
14
 
15
15
  **2. Paid, with a wallet.** Paid tools are settled in USDC on each call.
@@ -19,7 +19,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.22
19
19
  "mcpServers": {
20
20
  "agent402": {
21
21
  "command": "npx",
22
- "args": ["-y", "agent402-mcp@0.13.22"],
22
+ "args": ["-y", "agent402-mcp@0.13.25"],
23
23
  "env": { "AGENT_KEY": "0xYOUR_PRIVATE_KEY" }
24
24
  }
25
25
  }
@@ -30,7 +30,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.22
30
30
 
31
31
  Use `SOLANA_AGENT_KEY` instead for USDC on Solana. Each call is capped at $4 by default; there is no session budget unless you set `AGENT402_BUDGET`.
32
32
 
33
- Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.13.22`
33
+ Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.13.25`
34
34
  (use a new wallet holding only a few dollars of USDC; never your main wallet).
35
35
 
36
36
  Advanced setup (chains, MPP, error codes, the hosted connector) is in [Advanced](#advanced).
@@ -66,7 +66,7 @@ $4 per-call cap and no session budget). Set `AGENT402_BUDGET` to cap the session
66
66
  `payment.info` reports the caps, what's been spent, and what remains. With no wallet key and no credits key,
67
67
  the server runs in proof-of-work mode (pure-CPU tools stay free). Use dedicated
68
68
  low-value wallets for `AGENT_KEY` / `SOLANA_AGENT_KEY`, funded only with what
69
- you intend to spend. Most tools cost $0.001–$0.02. The routing tiers top out
69
+ you intend to spend. Most tools cost $0.001 to $0.02. The routing tiers top out
70
70
  at $3.30 (`route-execute-pro`); multi-tool skill packs run $0.003 to $0.101; and the
71
71
  report products run $0.60 to $2.00 per report (domain-audit $0.60 up to the ticker pack at $2.00),
72
72
  so the default per-call cap of $4 covers every tool; set `AGENT402_MAX_PER_CALL` lower for a
@@ -74,13 +74,13 @@ tighter ceiling.
74
74
 
75
75
  ## Advanced
76
76
 
77
- **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): a paid call answers JSON-RPC error `-32042` with the payment challenges, and `-32043` if a credential you presented was refused. 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.
77
+ **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.
78
78
 
79
79
  **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) 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`.
80
80
 
81
81
  **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.
82
82
 
83
- **Error codes.** `-32042` payment required (the challenges are in the error data). `-32043` a presented credential was refused.
83
+ **Error codes.** A first ask is a tool result, not an error (challenges in `_meta["org.paymentauth/payment-required"]`). `-32042` payment required on the tasks path (the challenges are in the error data). `-32043` a presented credential was refused.
84
84
 
85
85
  ## How it works
86
86
 
package/index.js CHANGED
@@ -61,14 +61,24 @@ const BASE = (process.env.AGENT402_URL || "https://agent402.tools").replace(/\/$
61
61
  // Catalog and seller requests (the 402 and the paid retry included) go through
62
62
  // a dedicated dispatcher that refuses a TLS chain through a distrusted
63
63
  // intermediate CA (networks.js).
64
- const ownFetch = distrustFetch();
64
+ // Every request names this package in its User-Agent (product token only), so
65
+ // the seller can tell which client a call came from. A caller's own
66
+ // User-Agent header, when one is set, is kept.
67
+ const plainFetch = distrustFetch();
68
+ const ownFetch = (input, init = {}) => {
69
+ // The payment wrapper passes a Request and no init: its headers are the base.
70
+ const h = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
71
+ if (!h.has("user-agent")) h.set("user-agent", `agent402-mcp/${VERSION}`);
72
+ return plainFetch(input, { ...init, headers: h });
73
+ };
65
74
  const AGENT_KEY = process.env.AGENT_KEY || "";
66
75
  // Solana secret key: base58 string (Phantom/solana-keygen export) or a JSON
67
76
  // byte array. Either key alone enables paid calls; with both, the buyer can
68
77
  // settle on whichever chain the seller offers (EVM accepts are tried first).
69
78
  const SOLANA_AGENT_KEY = process.env.SOLANA_AGENT_KEY || "";
70
79
  const HAS_WALLET = Boolean(AGENT_KEY || SOLANA_AGENT_KEY);
71
- // Prepaid card credits (no wallet): a key issued at https://agent402.tools/credits.
80
+ // A prepaid credits key (no wallet), already issued or bought where the
81
+ // service sells them (creditsSale() below reads which).
72
82
  // Sent as Authorization: Bearer on every catalog call; the server debits the
73
83
  // list price only on a successful (200) call and returns X-Credits-Balance.
74
84
  const CREDITS_KEY = (process.env.AGENT402_CREDITS_KEY || "").trim();
@@ -395,7 +405,7 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
395
405
 
396
406
  let res;
397
407
  if (!HAS_WALLET && HAS_CREDITS) {
398
- // Card credits: same budget guards as the wallet path, against the same
408
+ // Credits key: same budget guards as the wallet path, against the same
399
409
  // number - the credits gate holds and debits what the 402 quotes for THIS
400
410
  // body, not the route's list price.
401
411
  const listUsd = parseFloat(String(tool.price).replace(/[^0-9.]/g, "")) || 0;
@@ -415,7 +425,11 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
415
425
  if (res.ok) spentUsd += price;
416
426
  if (res.status === 402) {
417
427
  let body = {}; try { body = await res.clone().json(); } catch { /* plain */ }
418
- return { content: [{ type: "text", text: `Credits refused for "${tool.slug}": ${body.error || "payment required"}${body.balanceUsd != null ? ` (balance $${body.balanceUsd})` : ""}. Top up at ${body.topup || `${BASE}/credits`}.` }], isError: true };
428
+ // The refusal carries a topup link only while the service sells credits;
429
+ // otherwise its note says so and names where to pay per call instead.
430
+ const sale = creditsSale();
431
+ const next = body.topup ? `Top up at ${body.topup}.` : body.topupNote ? `${body.topupNote}${body.pay ? ` (${body.pay})` : ""}` : sale.buy ? `Top up at ${sale.buy}.` : `${sale.note[0].toUpperCase()}${sale.note.slice(1)}.`;
432
+ return { content: [{ type: "text", text: `Credits refused for "${tool.slug}": ${body.error || "payment required"}${body.balanceUsd != null ? ` (balance $${body.balanceUsd})` : ""}. ${next}` }], isError: true };
419
433
  }
420
434
  } else if (HAS_WALLET) {
421
435
  // The signing guard (installed on every key-built client, getPayFetch)
@@ -662,6 +676,17 @@ server.setRequestHandler(GetPromptRequestSchema, async (req) => {
662
676
  let curated = [];
663
677
  let pricingInfo = null;
664
678
 
679
+ // Whether the service sells new credits is a switch on the server, read from
680
+ // its /api/pricing (credits.onSale); this package cannot see the switch on its
681
+ // own, so a buy link is shown only while the catalog read says they are sold,
682
+ // and a key already issued keeps working either way.
683
+ function creditsSale() {
684
+ const c = pricingInfo?.credits;
685
+ if (c?.onSale === true) return { onSale: true, buy: c.buy || `${BASE}/credits` };
686
+ if (c?.onSale === false) return { onSale: false, note: "new credits are not on sale; a key already issued keeps working" };
687
+ return { onSale: null, note: `whether new credits are sold is read from ${BASE}/api/pricing (credits.onSale); a key already issued keeps working` };
688
+ }
689
+
665
690
  // A catalog that could not load at boot (a shed or unreachable service) is
666
691
  // read again on the next tools/list or tools/call, at most once per
667
692
  // CATALOG_RETRY_MS, so a session that started during a busy minute recovers
@@ -883,6 +908,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
883
908
  try { solanaAddress = (await solanaSigner()).address; } catch { solanaAddress = "invalid SOLANA_AGENT_KEY"; }
884
909
  }
885
910
  const computePayable = [...catalog.values()].filter((t) => t.computePayable).length;
911
+ const sale = creditsSale();
886
912
  return mcpJsonResult({
887
913
  service: BASE,
888
914
  mode: HAS_WALLET ? "usdc" : HAS_CREDITS ? "credits" : "proof-of-work",
@@ -894,7 +920,9 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
894
920
  payableWithCompute: computePayable,
895
921
  walletOnly: catalog.size - computePayable,
896
922
  workflows: skillPacks.length,
897
- credits: HAS_CREDITS ? { configured: true, how: "prepaid card credits (Authorization: Bearer a402_...) - every wallet-only tool except the wallet-identity-bound ones (memory, usage, receipts, attest, feedback) pays from the balance, debited only on a successful call", balance: `${BASE}/api/credits/balance`, topup: `${BASE}/credits` } : { configured: false, buy: `${BASE}/credits` },
923
+ credits: HAS_CREDITS
924
+ ? { configured: true, how: "a prepaid credits key (Authorization: Bearer a402_...) - every wallet-only tool except the wallet-identity-bound ones (memory, usage, receipts, attest, feedback) and the routes that buy from an outside seller pays from the balance, debited only on a successful call", balance: `${BASE}/api/credits/balance`, onSale: sale.onSale, ...(sale.buy ? { topup: sale.buy } : { note: sale.note }) }
925
+ : { configured: false, how: "a credits key, where sold or already issued, pays per successful call on Agent402's own services (AGENT402_CREDITS_KEY)", onSale: sale.onSale, ...(sale.buy ? { buy: sale.buy } : { note: sale.note }) },
898
926
  spendControls: (HAS_WALLET || HAS_CREDITS)
899
927
  ? {
900
928
  maxPerCallUsd: MAX_PER_CALL === Infinity ? "unlimited" : MAX_PER_CALL,
@@ -906,13 +934,13 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
906
934
  note: HAS_WALLET
907
935
  ? "Every tool is available; each call is paid in USDC via x402 from the configured wallet(s) - EVM chains via AGENT_KEY, Solana via SOLANA_AGENT_KEY - within the spend controls above."
908
936
  : HAS_CREDITS
909
- ? "Every tool on Agent402's own services is available; each call is paid from the prepaid card credits key (AGENT402_CREDITS_KEY), debited only on a successful call, within the spend controls above. The routes that buy from outside sellers (router.execute, seller-payability, decide.execute, the flight tools) and the wallet-identity tools (memory, usage) need a wallet key."
937
+ ? "Every tool on Agent402's own services is available; each call is paid from the credits key (AGENT402_CREDITS_KEY), debited only on a successful call, within the spend controls above. The routes that buy from outside sellers (router.execute, seller-payability, decide.execute, the flight tools) and the wallet-identity tools (memory, usage) need a wallet key."
910
938
  : `No wallet or credits key configured: ${computePayable} pure-CPU tools are free via proof-of-work; the ${catalog.size - computePayable} network/browser/memory tools need a funded wallet (AGENT_KEY / SOLANA_AGENT_KEY) or a prepaid credits key (AGENT402_CREDITS_KEY).`,
911
939
  install: {
912
940
  claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
913
941
  claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
914
942
  cursorHosted: { mcpServers: { agent402: { url: `${BASE}/mcp` } } },
915
- npm: "npx -y agent402-mcp@0.13.22",
943
+ npm: "npx -y agent402-mcp@0.13.25",
916
944
  maintainer: "Havok Holdings LLC",
917
945
  },
918
946
  positioning: `Flagship search/answer first, 500+ long-tail tools 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.`,
@@ -932,7 +960,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
932
960
  install: {
933
961
  claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
934
962
  claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
935
- npm: "npx -y agent402-mcp@0.13.22",
963
+ npm: "npx -y agent402-mcp@0.13.25",
936
964
  maintainer: "Havok Holdings LLC",
937
965
  },
938
966
  tools: catalog.size,
package/networks.js CHANGED
@@ -10,27 +10,23 @@
10
10
  // USDG on Robinhood Chain unreachable no matter what the wallet holds.
11
11
  import tls from "node:tls";
12
12
  import { createHash, X509Certificate } from "node:crypto";
13
+ import { NETWORK_NAMES, networkIdsOf } from "./known-assets.js";
13
14
 
14
- export const NETWORK_CAIP2 = {
15
- base: "eip155:8453",
16
- polygon: "eip155:137",
17
- arbitrum: "eip155:42161",
18
- "base-sepolia": "eip155:84532",
19
- robinhood: "eip155:4663",
20
- arc: "eip155:5042",
21
- solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
22
- "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
23
- };
15
+ /** Chain name -> its CAIP-2 id (the first id the known-asset table lists for
16
+ * that name), derived so a chain added there is named here too. */
17
+ export const NETWORK_CAIP2 = Object.freeze(Object.fromEntries(Object.entries(NETWORK_NAMES).map(([name, ids]) => [name, ids[0]])));
24
18
 
25
19
  /** Parse "robinhood,base" / "eip155:4663" into an ordered CAIP-2 list.
26
- * Unknown names pass through verbatim so raw CAIP-2 ids (future chains)
27
- * work without a package update. Returns [] when unset. */
20
+ * A chain name maps to every id the known-asset table lists for it (both
21
+ * Algorand spellings); unknown names pass through verbatim so raw CAIP-2
22
+ * ids (future chains) work without a package update. Returns [] when unset. */
28
23
  export function parseNetworkPrefs(raw) {
29
- return String(raw || "")
24
+ const ids = String(raw || "")
30
25
  .split(",")
31
26
  .map((s) => s.trim().toLowerCase())
32
27
  .filter(Boolean)
33
- .map((n) => NETWORK_CAIP2[n] || n);
28
+ .flatMap((n) => networkIdsOf(n));
29
+ return [...new Set(ids)];
34
30
  }
35
31
 
36
32
  /** Filter a 402's accepts to the preferred networks, ordered by preference
package/output-schemas.js CHANGED
@@ -492,7 +492,7 @@ export function mcpJsonResult(obj) {
492
492
  * Hosted URL is parameterized; npm / Claude Code / Cursor / Smithery notes
493
493
  * match docs/ecosystem-listings.md + wiki/MCP-Connector.md.
494
494
  */
495
- export const AGENT402_MCP_VERSION = "0.13.22";
495
+ export const AGENT402_MCP_VERSION = "0.13.25";
496
496
 
497
497
  /** A listed MCP tool description, at most `max` characters. Hosts truncate or
498
498
  * skip long descriptions, so the listing keeps the first whole sentences; the
@@ -524,12 +524,12 @@ export function mcpInstallHints(baseUrl) {
524
524
  mcpServers: {
525
525
  agent402: {
526
526
  command: "npx",
527
- args: ["-y", "agent402-mcp@0.13.22"],
527
+ args: ["-y", "agent402-mcp@0.13.25"],
528
528
  env: { AGENT_KEY: "0xYOUR_PRIVATE_KEY" },
529
529
  },
530
530
  },
531
531
  },
532
- npm: "npx -y agent402-mcp@0.13.22",
532
+ npm: "npx -y agent402-mcp@0.13.25",
533
533
  smithery: `Paste ${hosted} into the add-server form at https://smithery.ai/new. Submission is external; Agent402 does not auto-publish.`,
534
534
  maintainer: "Havok Holdings LLC",
535
535
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent402-mcp",
3
- "version": "0.13.22",
3
+ "version": "0.13.25",
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",
@@ -73,13 +73,13 @@
73
73
  ],
74
74
  "license": "MIT",
75
75
  "dependencies": {
76
- "@modelcontextprotocol/sdk": "^1.32.1",
77
- "@solana/kit": "^8.4.0",
76
+ "@modelcontextprotocol/sdk": "1.32.1",
77
+ "@solana/kit": "8.4.0",
78
78
  "@x402/core": "2.28.0",
79
79
  "@x402/evm": "2.28.0",
80
80
  "@x402/fetch": "2.28.0",
81
81
  "@x402/svm": "2.28.0",
82
- "viem": "^2.21.0"
82
+ "viem": "2.52.2"
83
83
  },
84
84
  "overrides": {
85
85
  "qs": "6.16.1",