agent402-mcp 0.13.29 → 0.13.31
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 +13 -6
- package/index.js +94 -25
- package/known-assets.js +86 -10
- package/output-schemas.js +3 -3
- package/package.json +2 -2
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.
|
|
12
|
+
claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.31
|
|
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.29
|
|
|
19
19
|
"mcpServers": {
|
|
20
20
|
"agent402": {
|
|
21
21
|
"command": "npx",
|
|
22
|
-
"args": ["-y", "agent402-mcp@0.13.
|
|
22
|
+
"args": ["-y", "agent402-mcp@0.13.31"],
|
|
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.29
|
|
|
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.
|
|
33
|
+
Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.13.31`
|
|
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).
|
|
@@ -80,13 +80,20 @@ seller that kept the authorization could still redeem it, so it counts against
|
|
|
80
80
|
(`https://agent402.tools`, matched by exact origin), an error status is never
|
|
81
81
|
settled, so a hold for one ends at the authorization's `validBefore` plus 10
|
|
82
82
|
minutes (15 minutes after the answer when no `validBefore` is readable). A held
|
|
83
|
-
amount whose authorization expires unused is released, never charged.
|
|
83
|
+
amount whose authorization expires unused is released, never charged. A payment
|
|
84
|
+
option asking to stay valid for more than a day is refused before anything is
|
|
85
|
+
signed, so no signed authorization outlives a day.
|
|
86
|
+
|
|
87
|
+
**Keys stay local.** `AGENT_KEY`, `SOLANA_AGENT_KEY` and `AGENT402_CREDITS_KEY`
|
|
88
|
+
are replaced with `[redacted]` wherever they would appear in a tool result, a
|
|
89
|
+
protocol error or a console line, and a key that does not parse is reported by
|
|
90
|
+
its variable name, not its value.
|
|
84
91
|
|
|
85
92
|
## Advanced
|
|
86
93
|
|
|
87
94
|
**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.
|
|
88
95
|
|
|
89
|
-
**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`.
|
|
96
|
+
**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`.
|
|
90
97
|
|
|
91
98
|
**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.
|
|
92
99
|
|
|
@@ -98,7 +105,7 @@ amount whose authorization expires unused is released, never charged.
|
|
|
98
105
|
- **Flagship tools** are exposed as first-class MCP tools under dotted names - `web.search`, `web.answer`, `web.news`, `browser.render`, `market.quote`, `audio.transcribe`, `memory.read`, `memory.write` - search/answer is the front door. Override the set with `AGENT402_TOOLS` (slugs; a non-flagship slug is listed as its snake_case name).
|
|
99
106
|
- **Decide** (`decide.plan`, `decide.execute`, `decide.feedback`): describe a job and get a call-ready plan over the catalog and outside x402 sellers (tools in order, fallbacks, validated params, chained steps), then run it yourself or through Agent402. Listed when the server offers Decide; see https://agent402.tools/decide.
|
|
100
107
|
- The rest of the 500+ tool catalog is reachable via the meta tools `catalog.search` / `catalog.find` + `catalog.call` - keeping your context window small. The same dotted names are listed on the hosted connector; the older snake names (`search_tools`, `find_tool`, `call_tool`, `get_payment_info`, `describe_server`, `list_top_sellers`, and the flagship `search_web` …) remain accepted as CallTool aliases, so existing configs keep working.
|
|
101
|
-
- When a call hits HTTP 402: with a wallet key set (`AGENT_KEY` for the EVM chains, Robinhood Chain included; `SOLANA_AGENT_KEY` for Solana), the server signs an x402 payment on a chain the seller accepts and retries; with only a credits key it sends `Authorization: Bearer a402_…` and the server debits the balance on success; with neither it solves the tool's proof-of-work challenge (~0.2 s of CPU) on the eligible tools. (The service settles USDC on Base, Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Arc, Stellar and Algorand, plus USDG on Robinhood Chain -
|
|
108
|
+
- When a call hits HTTP 402: with a wallet key set (`AGENT_KEY` for the EVM chains, Robinhood Chain included; `SOLANA_AGENT_KEY` for Solana), the server signs an x402 payment on a chain the seller accepts and retries; with only a credits key it sends `Authorization: Bearer a402_…` and the server debits the balance on success; with neither it solves the tool's proof-of-work challenge (~0.2 s of CPU) on the eligible tools. (The service settles USDC on Base, Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Arc, Ink, Stellar and Algorand, plus USDG on Robinhood Chain - 14 chains total - for callers using a raw x402 client rather than this package. Where the server also offers a Circle Gateway batched accept on Arc or Base, this package pays the plain accept beside it.)
|
|
102
109
|
- Since 0.13.15 the server's requests to the catalog and to sellers (catalog reads, the 402 and the paid retry) refuse a TLS chain through one of the intermediate CAs listed in `networks.js` (keys reported recoverable in Mozilla bug 2083449), keyed on each certificate's SubjectPublicKeyInfo hash, on a dedicated dispatcher. With a proxy or custom dispatcher installed, requests go out through it unchanged.
|
|
103
110
|
- **Slow routes run as jobs** (since 0.13.17): a paid call to a route the catalog marks slow carries `Prefer: respond-async`, answers `202` with a job link, and the server polls `GET /api/jobs/{id}` (free), waiting `Retry-After` seconds between polls, until the answer is ready, reading the job's `state` and falling back to its `status`. Payment settles only on the delivered answer. A caller that sends a `progressToken` gets `notifications/progress` from the job's stage, steps and ETA. A job still running when `AGENT402_ASYNC_TIMEOUT_MS` ends comes back with its `jobUrl` instead.
|
|
104
111
|
- `payment.info` tells the model which mode it's in and what a wallet or a credits key would unlock.
|
package/index.js
CHANGED
|
@@ -26,8 +26,9 @@
|
|
|
26
26
|
// Robinhood Chain, "base,solana", or a raw CAIP-2 like eip155:4663), optional
|
|
27
27
|
import { createHash } from "node:crypto";
|
|
28
28
|
import { readFileSync } from "node:fs";
|
|
29
|
+
import { format } from "node:util";
|
|
29
30
|
import { AsyncLocalStorage } from "node:async_hooks";
|
|
30
|
-
import { quoteOf, guardSigning } from "./known-assets.js";
|
|
31
|
+
import { quoteOf, guardSigning, signedExpirySeconds, MAX_VALIDITY_SECONDS } from "./known-assets.js";
|
|
31
32
|
import { parseNetworkPrefs, withNetworkPreference, distrustFetch } from "./networks.js";
|
|
32
33
|
import { fetchDiscovery, discoveryFailure, getDiscoveryJson } from "./discovery.js";
|
|
33
34
|
import { awaitJob, shouldRequestAsync, AsyncJobPendingError, DEFAULT_ASYNC_TIMEOUT_MS, jobState } from "./async-job.js";
|
|
@@ -88,6 +89,62 @@ const CREDITS_KEY = (process.env.AGENT402_CREDITS_KEY || "").trim();
|
|
|
88
89
|
const SHOW_ROUTER = HAS_WALLET || process.env.AGENT402_SHOW_ROUTER === "1";
|
|
89
90
|
const HIDDEN_WITHOUT_WALLET = new Set(["router.execute", META_MCP_NAMES.list_top_sellers]);
|
|
90
91
|
const HAS_CREDITS = /^a402_[A-Za-z0-9_-]{32,64}$/.test(CREDITS_KEY);
|
|
92
|
+
// The secrets this process holds never leave it in text: every tool result,
|
|
93
|
+
// every protocol error and every console line passes through redactSecrets,
|
|
94
|
+
// which replaces each configured key (and the spellings a library may print
|
|
95
|
+
// it in: without its 0x prefix, in either case, a byte array without spaces)
|
|
96
|
+
// with [redacted]. Key parsing also throws fixed messages that name the
|
|
97
|
+
// variable only (walletKeyError), since a parser's own message can quote its
|
|
98
|
+
// input.
|
|
99
|
+
const SECRET_FORMS = (() => {
|
|
100
|
+
const out = new Set();
|
|
101
|
+
for (const raw of [AGENT_KEY, SOLANA_AGENT_KEY, CREDITS_KEY]) {
|
|
102
|
+
const v = String(raw || "").trim();
|
|
103
|
+
if (v.length < 8) continue;
|
|
104
|
+
out.add(v);
|
|
105
|
+
const hex = v.replace(/^0x/i, "");
|
|
106
|
+
if (/^[0-9a-f]+$/i.test(hex) && hex.length >= 8) { out.add(hex); out.add(hex.toLowerCase()); out.add(hex.toUpperCase()); }
|
|
107
|
+
if (v.startsWith("[")) out.add(v.replace(/\s+/g, ""));
|
|
108
|
+
}
|
|
109
|
+
return [...out].sort((a, b) => b.length - a.length);
|
|
110
|
+
})();
|
|
111
|
+
function redactSecrets(text) {
|
|
112
|
+
let t = String(text);
|
|
113
|
+
for (const f of SECRET_FORMS) if (t.includes(f)) t = t.split(f).join("[redacted]");
|
|
114
|
+
return t;
|
|
115
|
+
}
|
|
116
|
+
/** A copy of a tool result (or any JSON value) with every string redacted. */
|
|
117
|
+
function redactDeep(v, depth = 0) {
|
|
118
|
+
if (!SECRET_FORMS.length) return v;
|
|
119
|
+
if (typeof v === "string") return redactSecrets(v);
|
|
120
|
+
if (depth > 64 || v == null || typeof v !== "object") return v;
|
|
121
|
+
if (Array.isArray(v)) return v.map((x) => redactDeep(x, depth + 1));
|
|
122
|
+
const out = {};
|
|
123
|
+
for (const [k, x] of Object.entries(v)) out[k] = redactDeep(x, depth + 1);
|
|
124
|
+
return out;
|
|
125
|
+
}
|
|
126
|
+
/** A handler whose answer, and whose thrown error's message, are redacted. */
|
|
127
|
+
const redacted = (handler) => async (req, extra) => {
|
|
128
|
+
try {
|
|
129
|
+
return redactDeep(await handler(req, extra));
|
|
130
|
+
} catch (e) {
|
|
131
|
+
if (SECRET_FORMS.length && e && typeof e.message === "string") {
|
|
132
|
+
try { e.message = redactSecrets(e.message); if (typeof e.stack === "string") e.stack = redactSecrets(e.stack); } catch { /* a frozen error */ throw new Error(redactSecrets(e.message)); }
|
|
133
|
+
}
|
|
134
|
+
throw e;
|
|
135
|
+
}
|
|
136
|
+
};
|
|
137
|
+
// Every console line, a library's included, is redacted before it is written.
|
|
138
|
+
if (SECRET_FORMS.length) {
|
|
139
|
+
for (const m of ["log", "info", "warn", "error", "debug", "trace"]) {
|
|
140
|
+
const orig = console[m].bind(console);
|
|
141
|
+
console[m] = (...a) => orig(redactSecrets(format(...a)));
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
/** A fixed error for a key that does not parse: the variable's name, never
|
|
145
|
+
* the parser's message (it can quote the value). */
|
|
146
|
+
const walletKeyError = (name, what) => new Error(`${name} is set but is not ${what}; check the value (it is never printed)`);
|
|
147
|
+
|
|
91
148
|
// Slow paid routes (async.recommended on their /api/pricing row) are sent with
|
|
92
149
|
// Prefer: respond-async and collected from their job link (./async-job.js).
|
|
93
150
|
// AGENT402_ASYNC=off waits on the connection instead; =always uses a job on
|
|
@@ -114,7 +171,7 @@ const capFromEnv = (name, def) => {
|
|
|
114
171
|
if (raw === "off") return Infinity;
|
|
115
172
|
const n = Number(raw);
|
|
116
173
|
if (Number.isFinite(n) && n >= 0) return n;
|
|
117
|
-
console.error(`[agent402-mcp] ${name}=${JSON.stringify(process.env[name])} is not a USD amount or "off"; using the default (${def === Infinity ? "no cap" : `$${def}`})`);
|
|
174
|
+
console.error(`[agent402-mcp] ${name}=${String(process.env[name]).length <= 16 ? JSON.stringify(process.env[name]) : "(a long value, not shown)"} is not a USD amount or "off"; using the default (${def === Infinity ? "no cap" : `$${def}`})`);
|
|
118
175
|
return def;
|
|
119
176
|
};
|
|
120
177
|
const MAX_PER_CALL = capFromEnv("AGENT402_MAX_PER_CALL", DEFAULT_MAX_PER_CALL_USD);
|
|
@@ -136,12 +193,13 @@ const holds = []; // [{ usd, until }], until Infinity = the rest of the session
|
|
|
136
193
|
const holdPayment = (usd, until = Infinity) => { holds.push({ usd, until }); };
|
|
137
194
|
const heldNow = () => { const now = Date.now(); let t = 0; for (const h of holds) if (h.until > now) t += h.usd; return t; };
|
|
138
195
|
/** When a sent payload can no longer settle plus the clock slack: an EIP-3009
|
|
139
|
-
* validBefore or a Permit2 deadline, in seconds
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
196
|
+
* validBefore or a Permit2 deadline, in seconds, never later than
|
|
197
|
+
* MAX_VALIDITY_SECONDS from now (the signing guard refuses to send a payload
|
|
198
|
+
* valid for longer); null when none is readable. */
|
|
199
|
+
function signedValidUntilMs(paymentPayload, nowMs = Date.now()) {
|
|
200
|
+
const v = signedExpirySeconds(paymentPayload);
|
|
201
|
+
if (v == null || !Number.isFinite(v)) return null;
|
|
202
|
+
return Math.min(v * 1000, nowMs + MAX_VALIDITY_SECONDS * 1000) + HOLD_SLACK_MS;
|
|
145
203
|
}
|
|
146
204
|
// Wallet calls in flight, each holding what it may sign until it settles or
|
|
147
205
|
// fails, so concurrent calls cannot each pass against the same budget. The
|
|
@@ -248,7 +306,7 @@ function getPayFetch() {
|
|
|
248
306
|
if (AGENT_KEY) {
|
|
249
307
|
const { registerExactEvmScheme } = await import("@x402/evm/exact/client");
|
|
250
308
|
const { privateKeyToAccount } = await import("viem/accounts");
|
|
251
|
-
registerExactEvmScheme(client, { signer: privateKeyToAccount
|
|
309
|
+
registerExactEvmScheme(client, { signer: evmAccount(privateKeyToAccount) });
|
|
252
310
|
}
|
|
253
311
|
if (SOLANA_AGENT_KEY) {
|
|
254
312
|
const { registerExactSvmScheme } = await import("@x402/svm/exact/client");
|
|
@@ -265,6 +323,11 @@ function getPayFetch() {
|
|
|
265
323
|
return payFetchPromise;
|
|
266
324
|
}
|
|
267
325
|
|
|
326
|
+
/** The viem account for AGENT_KEY, or walletKeyError. */
|
|
327
|
+
function evmAccount(privateKeyToAccount) {
|
|
328
|
+
try { return privateKeyToAccount(AGENT_KEY.trim()); } catch { throw walletKeyError("AGENT_KEY", "a 0x-prefixed 32-byte hex private key"); }
|
|
329
|
+
}
|
|
330
|
+
|
|
268
331
|
// @solana/kit KeyPairSigner from SOLANA_AGENT_KEY, base58 64-byte secret key
|
|
269
332
|
// (Phantom / solana-keygen export) or a JSON byte array ([12,34,…]).
|
|
270
333
|
let solanaSignerPromise;
|
|
@@ -272,10 +335,14 @@ function solanaSigner() {
|
|
|
272
335
|
solanaSignerPromise ??= (async () => {
|
|
273
336
|
const { createKeyPairSignerFromBytes, getBase58Encoder } = await import("@solana/kit");
|
|
274
337
|
const raw = SOLANA_AGENT_KEY.trim();
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
338
|
+
try {
|
|
339
|
+
const bytes = raw.startsWith("[")
|
|
340
|
+
? Uint8Array.from(JSON.parse(raw))
|
|
341
|
+
: new Uint8Array(getBase58Encoder().encode(raw));
|
|
342
|
+
return await createKeyPairSignerFromBytes(bytes);
|
|
343
|
+
} catch {
|
|
344
|
+
throw walletKeyError("SOLANA_AGENT_KEY", "a base58 or JSON byte-array 64-byte Solana secret key");
|
|
345
|
+
}
|
|
279
346
|
})();
|
|
280
347
|
return solanaSignerPromise;
|
|
281
348
|
}
|
|
@@ -561,8 +628,10 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
|
|
|
561
628
|
function signingRefusal(tool, d) {
|
|
562
629
|
const text = d.reason === "unknown-asset"
|
|
563
630
|
? `Refused without paying: "${tool.slug}" asked to be paid in an asset this server cannot price (USDC or USDG on a known network), so nothing was signed.`
|
|
564
|
-
: d.reason === "signed-amount"
|
|
631
|
+
: d.reason === "signed-amount" || d.reason === "signed-validity"
|
|
565
632
|
? `Refused without paying: for "${tool.slug}", ${d.detail}, so the payment was not sent.`
|
|
633
|
+
: d.reason === "validity"
|
|
634
|
+
? `Refused without paying: for "${tool.slug}", ${d.detail}, so nothing was signed.`
|
|
566
635
|
: `Refused without paying: "${tool.slug}" asked for $${d.priceUsd} on the paid request, above the $${Number(d.allowanceUsd.toFixed(6))} this server may sign (AGENT402_MAX_PER_CALL ${MAX_PER_CALL === Infinity ? "off" : `$${MAX_PER_CALL}`}, AGENT402_BUDGET ${BUDGET === Infinity ? "off" : `$${BUDGET}`} with $${spentUsd.toFixed(4)} spent). Nothing was signed.`;
|
|
567
636
|
return { content: [{ type: "text", text }], isError: true };
|
|
568
637
|
}
|
|
@@ -689,7 +758,7 @@ const server = new Server(
|
|
|
689
758
|
// MCP-aware client. The list is fetched once at boot in loadCatalog(); the
|
|
690
759
|
// per-prompt rendering is delegated to the hosted service so the npm package
|
|
691
760
|
// stays thin and prompt text stays canonical with the website at /skills.
|
|
692
|
-
server.setRequestHandler(ListPromptsRequestSchema, async () => ({
|
|
761
|
+
server.setRequestHandler(ListPromptsRequestSchema, redacted(async () => ({
|
|
693
762
|
prompts: skillPacks.map((p) => ({
|
|
694
763
|
name: p.slug,
|
|
695
764
|
title: p.title,
|
|
@@ -700,8 +769,8 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => ({
|
|
|
700
769
|
required: a.required ?? true,
|
|
701
770
|
})),
|
|
702
771
|
})),
|
|
703
|
-
}));
|
|
704
|
-
server.setRequestHandler(GetPromptRequestSchema, async (req) => {
|
|
772
|
+
})));
|
|
773
|
+
server.setRequestHandler(GetPromptRequestSchema, redacted(async (req) => {
|
|
705
774
|
const { name, arguments: args = {} } = req.params;
|
|
706
775
|
const pack = skillPacks.find((p) => p.slug === name);
|
|
707
776
|
if (!pack) throw new Error(`Unknown prompt "${name}". List available with prompts/list.`);
|
|
@@ -712,7 +781,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (req) => {
|
|
|
712
781
|
const { res, attempts } = await fetchDiscovery(url);
|
|
713
782
|
if (!res.ok) throw new Error(`Failed to render prompt "${name}" from ${BASE}: ${discoveryFailure(url, res, attempts)}`);
|
|
714
783
|
return await res.json();
|
|
715
|
-
});
|
|
784
|
+
}));
|
|
716
785
|
|
|
717
786
|
let curated = [];
|
|
718
787
|
let pricingInfo = null;
|
|
@@ -747,7 +816,7 @@ async function ensureCatalog() {
|
|
|
747
816
|
}
|
|
748
817
|
const withCatalog = (handler) => async (req, extra) => { await ensureCatalog(); return handler(req, extra); };
|
|
749
818
|
|
|
750
|
-
server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
|
|
819
|
+
server.setRequestHandler(ListToolsRequestSchema, redacted(withCatalog(async () => {
|
|
751
820
|
// Read-only only for lookups that stay on this machine (describe, payment
|
|
752
821
|
// info). Anything that reaches the network or can spend is NET: not read-only,
|
|
753
822
|
// open-world. A host reads readOnlyHint to decide whether to ask first.
|
|
@@ -878,9 +947,9 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
|
|
|
878
947
|
// AGENT402_SHOW_ROUTER=1 opts in. Calls to them still route when unlisted.
|
|
879
948
|
const listed = SHOW_ROUTER ? tools : tools.filter((t) => !HIDDEN_WITHOUT_WALLET.has(t.name));
|
|
880
949
|
return { tools: listed };
|
|
881
|
-
}));
|
|
950
|
+
})));
|
|
882
951
|
|
|
883
|
-
server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) => {
|
|
952
|
+
server.setRequestHandler(CallToolRequestSchema, redacted(withCatalog(async (req, extra) => {
|
|
884
953
|
const { name: rawName, arguments: args = {} } = req.params;
|
|
885
954
|
const name = resolveListedName(rawName);
|
|
886
955
|
const overBound = toolInputBoundRefusal(rawName, args);
|
|
@@ -942,7 +1011,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
|
|
|
942
1011
|
let address = null;
|
|
943
1012
|
if (AGENT_KEY) {
|
|
944
1013
|
const { privateKeyToAccount } = await import("viem/accounts");
|
|
945
|
-
address = privateKeyToAccount
|
|
1014
|
+
try { address = evmAccount(privateKeyToAccount).address; } catch { address = "invalid AGENT_KEY"; }
|
|
946
1015
|
}
|
|
947
1016
|
let solanaAddress = null;
|
|
948
1017
|
if (SOLANA_AGENT_KEY) {
|
|
@@ -982,7 +1051,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
|
|
|
982
1051
|
claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
|
|
983
1052
|
claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
|
|
984
1053
|
cursorHosted: { mcpServers: { agent402: { url: `${BASE}/mcp` } } },
|
|
985
|
-
npm: "npx -y agent402-mcp@0.13.
|
|
1054
|
+
npm: "npx -y agent402-mcp@0.13.31",
|
|
986
1055
|
maintainer: "Havok Holdings LLC",
|
|
987
1056
|
},
|
|
988
1057
|
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.`,
|
|
@@ -1002,7 +1071,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
|
|
|
1002
1071
|
install: {
|
|
1003
1072
|
claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
|
|
1004
1073
|
claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
|
|
1005
|
-
npm: "npx -y agent402-mcp@0.13.
|
|
1074
|
+
npm: "npx -y agent402-mcp@0.13.31",
|
|
1006
1075
|
maintainer: "Havok Holdings LLC",
|
|
1007
1076
|
},
|
|
1008
1077
|
tools: catalog.size,
|
|
@@ -1143,7 +1212,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
|
|
|
1143
1212
|
} catch (err) {
|
|
1144
1213
|
return { content: [{ type: "text", text: `Agent402 call failed: ${err.message}` }], isError: true };
|
|
1145
1214
|
}
|
|
1146
|
-
}));
|
|
1215
|
+
})));
|
|
1147
1216
|
|
|
1148
1217
|
// ---------------------------------------------------------------------------
|
|
1149
1218
|
try {
|
package/known-assets.js
CHANGED
|
@@ -12,6 +12,12 @@
|
|
|
12
12
|
// and a buyer with a cap does not sign it. The table is keyed by CAIP-2 ids
|
|
13
13
|
// only: a bare v1 network name (for example "base") is not priced.
|
|
14
14
|
//
|
|
15
|
+
// An entry may also name its token's EIP-712 domain (`name` and `version`,
|
|
16
|
+
// read from the token's own name() and version()). An EVM "exact" signer
|
|
17
|
+
// signs under the domain the accept's `extra` carries, so for such an entry
|
|
18
|
+
// an accept whose `extra.name` or `extra.version` is not exactly the token's
|
|
19
|
+
// cannot be priced either, and a buyer with a cap does not sign it.
|
|
20
|
+
//
|
|
15
21
|
// The same file ships in agent402-client, agent402-mcp and agent402-openclaw;
|
|
16
22
|
// the parent repo's scripts/test-known-assets.js keeps the copies identical and
|
|
17
23
|
// checks the table against the assets the server offers.
|
|
@@ -29,6 +35,7 @@ export const KNOWN_ASSETS = Object.freeze({
|
|
|
29
35
|
"eip155:1329": [{ asset: "0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392", decimals: 6, symbol: "USDC" }], // Sei
|
|
30
36
|
"eip155:10": [{ asset: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", decimals: 6, symbol: "USDC" }], // Optimism
|
|
31
37
|
"eip155:5042": [{ asset: "0x3600000000000000000000000000000000000000", decimals: 6, symbol: "USDC" }], // Arc
|
|
38
|
+
"eip155:57073": [{ asset: "0x2D270e6886d130D724215A266106e6832161EAEd", decimals: 6, symbol: "USDC", name: "USDC", version: "2" }], // Ink
|
|
32
39
|
"eip155:4663": [{ asset: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", decimals: 6, symbol: "USDG" }], // Robinhood Chain
|
|
33
40
|
// Solana: the USDC mint.
|
|
34
41
|
"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [{ asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", decimals: 6, symbol: "USDC" }],
|
|
@@ -56,6 +63,7 @@ export const NETWORK_NAMES = Object.freeze({
|
|
|
56
63
|
sei: ["eip155:1329"],
|
|
57
64
|
optimism: ["eip155:10"],
|
|
58
65
|
arc: ["eip155:5042"],
|
|
66
|
+
ink: ["eip155:57073"],
|
|
59
67
|
robinhood: ["eip155:4663"],
|
|
60
68
|
solana: ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
|
|
61
69
|
"solana-devnet": ["solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"],
|
|
@@ -88,6 +96,15 @@ export function knownAsset(network, asset) {
|
|
|
88
96
|
return list.find((e) => sameAsset(e.asset, asset)) || null;
|
|
89
97
|
}
|
|
90
98
|
|
|
99
|
+
/** True when the accept carries the EIP-712 domain the table names for its
|
|
100
|
+
* asset (`extra.name` and `extra.version`, exactly), or when the entry names
|
|
101
|
+
* none. */
|
|
102
|
+
export function acceptDomainMatches(entry, accept) {
|
|
103
|
+
if (!entry || (entry.name == null && entry.version == null)) return true;
|
|
104
|
+
const extra = accept && typeof accept.extra === "object" && accept.extra ? accept.extra : {};
|
|
105
|
+
return extra.name === entry.name && extra.version === entry.version;
|
|
106
|
+
}
|
|
107
|
+
|
|
91
108
|
/** The base-unit amount the signer of `x402Version` signs for one accept, as
|
|
92
109
|
* a string of digits: `maxAmountRequired` under v1, `amount` under v2. With
|
|
93
110
|
* no version, the one field present (or both, when they agree). null when
|
|
@@ -111,12 +128,13 @@ export function acceptAmount(accept, x402Version = undefined) {
|
|
|
111
128
|
|
|
112
129
|
/** The USD value of one accept: the base-unit amount its version's signer
|
|
113
130
|
* signs (acceptAmount) over the KNOWN decimals of its asset. null when the
|
|
114
|
-
* asset is not known
|
|
131
|
+
* asset is not known, when the accept names a different EIP-712 domain than
|
|
132
|
+
* the table's for that asset, or when the amount cannot be read. */
|
|
115
133
|
export function acceptUsd(accept, x402Version = undefined) {
|
|
116
134
|
const raw = acceptAmount(accept, x402Version);
|
|
117
135
|
if (raw == null) return null;
|
|
118
136
|
const entry = knownAsset(accept.network, accept.asset);
|
|
119
|
-
if (!entry) return null;
|
|
137
|
+
if (!entry || !acceptDomainMatches(entry, accept)) return null;
|
|
120
138
|
return Number(raw) / 10 ** entry.decimals;
|
|
121
139
|
}
|
|
122
140
|
|
|
@@ -134,6 +152,51 @@ export function quoteOf(accepts, x402Version = undefined) {
|
|
|
134
152
|
return { max, min, unknown, total: accepts.length };
|
|
135
153
|
}
|
|
136
154
|
|
|
155
|
+
// The longest a signed payment may stay redeemable. An EVM "exact" signer
|
|
156
|
+
// sets validBefore (EIP-3009) or deadline (Permit2) to the moment of signing
|
|
157
|
+
// plus the accept's maxTimeoutSeconds, and the signed payload is a bearer
|
|
158
|
+
// claim until then, so a seller that quotes years gets an authorization it
|
|
159
|
+
// could redeem for years and a held amount that never stops counting. Honest
|
|
160
|
+
// accepts ask for minutes (Agent402's own ask 300 s); a day admits every
|
|
161
|
+
// one of them. An accept that asks for longer is dropped before selection,
|
|
162
|
+
// and a payload signed past it is refused before it is sent.
|
|
163
|
+
export const MAX_VALIDITY_SECONDS = 24 * 3600;
|
|
164
|
+
// Signing reads the clock a moment before the check after it does.
|
|
165
|
+
const VALIDITY_CLOCK_SLACK_SECONDS = 60;
|
|
166
|
+
|
|
167
|
+
/** True when an accept asks for a validity window past MAX_VALIDITY_SECONDS.
|
|
168
|
+
* An accept with no readable maxTimeoutSeconds is left to the check of what
|
|
169
|
+
* was signed (signedValidityProblem). */
|
|
170
|
+
export function acceptValidityTooLong(accept, maxSeconds = MAX_VALIDITY_SECONDS) {
|
|
171
|
+
const raw = accept?.maxTimeoutSeconds;
|
|
172
|
+
if (raw == null || raw === "") return false;
|
|
173
|
+
const n = Number(raw);
|
|
174
|
+
return !Number.isFinite(n) || n > maxSeconds;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** The expiry a signed payload carries, in unix seconds: an EIP-3009
|
|
178
|
+
* `authorization.validBefore` or a Permit2 `deadline`. null when the payload
|
|
179
|
+
* names none (a Solana transaction, an unknown scheme). NaN when it names
|
|
180
|
+
* one that is not a whole number of seconds. */
|
|
181
|
+
export function signedExpirySeconds(paymentPayload) {
|
|
182
|
+
const p = paymentPayload?.payload;
|
|
183
|
+
const v = p?.authorization?.validBefore ?? p?.permit2Authorization?.deadline;
|
|
184
|
+
if (v == null) return null;
|
|
185
|
+
return /^\d{1,15}$/.test(String(v)) ? Number(v) : NaN;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** Why a created payment payload stays redeemable for too long, or null: its
|
|
189
|
+
* expiry is past `nowMs` plus `maxSeconds` (and a minute of clock slack), or
|
|
190
|
+
* it names an expiry that cannot be read. */
|
|
191
|
+
export function signedValidityProblem(paymentPayload, { maxSeconds = MAX_VALIDITY_SECONDS, nowMs = Date.now() } = {}) {
|
|
192
|
+
const exp = signedExpirySeconds(paymentPayload);
|
|
193
|
+
if (exp == null) return null;
|
|
194
|
+
if (!Number.isFinite(exp)) return "the signed authorization's expiry cannot be read";
|
|
195
|
+
const left = exp - Math.floor(nowMs / 1000);
|
|
196
|
+
if (left > maxSeconds + VALIDITY_CLOCK_SLACK_SECONDS) return `the signed authorization stays valid for ${left} seconds, past the ${maxSeconds}-second ceiling`;
|
|
197
|
+
return null;
|
|
198
|
+
}
|
|
199
|
+
|
|
137
200
|
/** Enforce a USD allowance at signing on an @x402/core x402Client.
|
|
138
201
|
*
|
|
139
202
|
* `allowance()` is the most this buyer may sign for the payment being built
|
|
@@ -141,8 +204,10 @@ export function quoteOf(accepts, x402Version = undefined) {
|
|
|
141
204
|
* for none). A registered policy drops every accept that cannot be priced or
|
|
142
205
|
* is over the allowance, so the client selects among the ones that fit, and a
|
|
143
206
|
* hook before payload creation checks the selected accept again and passes
|
|
144
|
-
* its USD value to `onSign`.
|
|
145
|
-
*
|
|
207
|
+
* its USD value to `onSign`. An accept asking for a validity window past
|
|
208
|
+
* MAX_VALIDITY_SECONDS is dropped and refused the same way. A refusal throws
|
|
209
|
+
* (from the policy) or aborts (from the hook) before any signature exists;
|
|
210
|
+
* `onRefuse` hears why first. */
|
|
146
211
|
export function guardSigning(client, { allowance, onSign = null, onRefuse = null }) {
|
|
147
212
|
if (!client || typeof client.registerPolicy !== "function" || typeof client.onBeforePaymentCreation !== "function") {
|
|
148
213
|
throw new TypeError("guardSigning needs an @x402/core x402Client (registerPolicy and onBeforePaymentCreation)");
|
|
@@ -151,7 +216,12 @@ export function guardSigning(client, { allowance, onSign = null, onRefuse = null
|
|
|
151
216
|
const refuse = (detail) => { try { onRefuse?.(detail); } catch { /* the refusal stands */ } return detail; };
|
|
152
217
|
client.registerPolicy((version, accepts) => {
|
|
153
218
|
const cap = allowance();
|
|
154
|
-
const
|
|
219
|
+
const priced = accepts.filter((a) => { const usd = acceptUsd(a, version); return usd != null && usd <= cap; });
|
|
220
|
+
const kept = priced.filter((a) => !acceptValidityTooLong(a));
|
|
221
|
+
if (!kept.length && priced.length) {
|
|
222
|
+
const d = refuse({ reason: "validity", priceUsd: null, allowanceUsd: cap, detail: `every payment option it may sign asks to stay valid for more than ${MAX_VALIDITY_SECONDS} seconds` });
|
|
223
|
+
throw new Error(`spending guard: ${d.detail}; nothing was signed`);
|
|
224
|
+
}
|
|
155
225
|
if (!kept.length) {
|
|
156
226
|
const q = quoteOf(accepts, version);
|
|
157
227
|
const d = refuse({ reason: q && q.min != null ? "over-allowance" : "unknown-asset", priceUsd: q ? q.min : null, allowanceUsd: cap });
|
|
@@ -172,6 +242,10 @@ export function guardSigning(client, { allowance, onSign = null, onRefuse = null
|
|
|
172
242
|
refuse({ reason: "over-allowance", priceUsd: usd, allowanceUsd: cap });
|
|
173
243
|
return { abort: true, reason: `spending guard: the selected payment option asks $${usd}, above the $${cap} this buyer may sign; nothing was signed` };
|
|
174
244
|
}
|
|
245
|
+
if (acceptValidityTooLong(r)) {
|
|
246
|
+
const d = refuse({ reason: "validity", priceUsd: usd, allowanceUsd: cap, detail: `the selected payment option asks to stay valid for ${r.maxTimeoutSeconds} seconds, past the ${MAX_VALIDITY_SECONDS}-second ceiling` });
|
|
247
|
+
return { abort: true, reason: `spending guard: ${d.detail}; nothing was signed` };
|
|
248
|
+
}
|
|
175
249
|
onSign?.(usd, r);
|
|
176
250
|
return undefined;
|
|
177
251
|
});
|
|
@@ -252,9 +326,10 @@ export async function signedPaymentProblem(paymentPayload, requirements, x402Ver
|
|
|
252
326
|
}
|
|
253
327
|
|
|
254
328
|
/** Refuse to send a payment payload whose signed amount is not the one the
|
|
255
|
-
* allowance passed
|
|
256
|
-
*
|
|
257
|
-
*
|
|
329
|
+
* allowance passed, or whose expiry is past MAX_VALIDITY_SECONDS from now
|
|
330
|
+
* (signedValidityProblem): registered after payload creation, so the check
|
|
331
|
+
* reads what was actually signed, and a throw here stops the payment-aware
|
|
332
|
+
* fetch before the payload leaves the process. guardSigning registers it; a
|
|
258
333
|
* client with its own selector (and no guardSigning) can register it alone. */
|
|
259
334
|
export function guardSignedAmount(client, { allowance = () => Infinity, onRefuse = null } = {}) {
|
|
260
335
|
if (!client || typeof client.onAfterPaymentCreation !== "function") {
|
|
@@ -262,9 +337,10 @@ export function guardSignedAmount(client, { allowance = () => Infinity, onRefuse
|
|
|
262
337
|
}
|
|
263
338
|
client.onAfterPaymentCreation(async ({ paymentRequired, selectedRequirements: r, paymentPayload }) => {
|
|
264
339
|
const cap = allowance();
|
|
265
|
-
const
|
|
340
|
+
const amountProblem = await signedPaymentProblem(paymentPayload, r, paymentRequired?.x402Version, cap);
|
|
341
|
+
const problem = amountProblem || signedValidityProblem(paymentPayload);
|
|
266
342
|
if (!problem) return;
|
|
267
|
-
try { onRefuse?.({ reason: "signed-amount", priceUsd: null, allowanceUsd: cap, detail: problem }); } catch { /* the refusal stands */ }
|
|
343
|
+
try { onRefuse?.({ reason: amountProblem ? "signed-amount" : "signed-validity", priceUsd: null, allowanceUsd: cap, detail: problem }); } catch { /* the refusal stands */ }
|
|
268
344
|
throw new Error(`spending guard: ${problem}; the payment was not sent`);
|
|
269
345
|
});
|
|
270
346
|
return client;
|
package/output-schemas.js
CHANGED
|
@@ -492,7 +492,7 @@ export function mcpJsonResult(obj) {
|
|
|
492
492
|
* Hosted URL is parameterized; npm / Claude Code / Cursor notes
|
|
493
493
|
* match docs/ecosystem-listings.md + wiki/MCP-Connector.md.
|
|
494
494
|
*/
|
|
495
|
-
export const AGENT402_MCP_VERSION = "0.13.
|
|
495
|
+
export const AGENT402_MCP_VERSION = "0.13.31";
|
|
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.
|
|
527
|
+
args: ["-y", "agent402-mcp@0.13.31"],
|
|
528
528
|
env: { AGENT_KEY: "0xYOUR_PRIVATE_KEY" },
|
|
529
529
|
},
|
|
530
530
|
},
|
|
531
531
|
},
|
|
532
|
-
npm: "npx -y agent402-mcp@0.13.
|
|
532
|
+
npm: "npx -y agent402-mcp@0.13.31",
|
|
533
533
|
maintainer: "Havok Holdings LLC",
|
|
534
534
|
};
|
|
535
535
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent402-mcp",
|
|
3
|
-
"version": "0.13.
|
|
3
|
+
"version": "0.13.31",
|
|
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",
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
"url": "git+https://github.com/MikeyPetrillo/Agent402.git",
|
|
10
10
|
"directory": "mcp"
|
|
11
11
|
},
|
|
12
|
-
"description": "Agent402 MCP server: 500+ pay-per-call tools + skill packs for AI agents over x402 (USDC or USDG on
|
|
12
|
+
"description": "Agent402 MCP server: 500+ pay-per-call tools + skill packs for AI agents over x402 (USDC or USDG on 14 chains) or MPP on the same 402, or free via proof-of-work - the applied layer of Agentic Finance. Catalog: browser, web search + cited answers, PDFs, OCR, images, LLM inference, image generation, code execution, STT, embeddings, live financial/crypto/macro data, SEC EDGAR filings, deterministic stats & forecasting, compression, payments. Open source, self-hostable.",
|
|
13
13
|
"type": "module",
|
|
14
14
|
"bin": {
|
|
15
15
|
"agent402-mcp": "index.js"
|