verify402-mcp 1.0.9 → 1.1.1

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/.env.example CHANGED
@@ -17,6 +17,12 @@ SPEND_LEDGER_PATH= # optional override for the ledger file (default .spen
17
17
  # Base Sepolia testnet: the live demo's EVM payment rail.
18
18
  VERIFY402_NETWORKS=eip155:84532
19
19
  VERIFY402_PAY_TO=0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb
20
+
21
+ # Anonymous usage telemetry, opt-in. When set to 1 the bridge sends one
22
+ # fire-and-forget line per tool call to the service: the tool name and whether
23
+ # it worked. Never arguments, intents, results, wallet data, or IPs. Default is
24
+ # off, and a failed ping never changes a tool's answer.
25
+ # VERIFY402_TELEMETRY=1
20
26
  # VERIFY402_RESOURCE_PREFIX=https://verify402.onrender.com
21
27
  # Explicit mainnet is a separate deployment, not a demo setting. Set this only
22
28
  # after separate readiness verification, with a mainnet facilitator and host:
package/README.md CHANGED
@@ -18,18 +18,32 @@ payments. The bridge never signs or sends a trade.
18
18
  > immutable, and `1.0.4` used Base mainnet by default. Do not republish or
19
19
  > overwrite any of them.
20
20
 
21
+ ## Anonymous usage telemetry (opt-in)
22
+
23
+ The bridge can send one anonymous line per tool call to the service: the tool
24
+ name and whether it succeeded (`POST /usage/ping`). Never arguments, intents,
25
+ results, wallet data, or IPs. Off by default; set `VERIFY402_TELEMETRY=1` to
26
+ turn it on. A failed ping never changes the tool's answer, and only these
27
+ tool names are accepted: `preflight_gate`, `inspect_402`, `directory_402`,
28
+ `verify_arbitrage`, `check_token_safety`, `get_best_route`,
29
+ `verify_quote_fairness`, `get_trade_depth`.
30
+
21
31
  ## Tools
22
32
 
23
33
  | tool | price | what it answers |
24
34
  |---|---|---|
25
35
  | `preflight_gate` | **free** | "Should I sign this payment request or transaction?" — PASS / CAUTION / BLOCK with reasons, `checked` / `notChecked`, and a short-lived receipt |
36
+ | `inspect_402` | **free** | "What does this 402 actually ask for?" — price, token, network, payee, bound resource, and a PASS / CAUTION / BLOCK verdict from a read-only fetch |
37
+ | `directory_402` | **free** | "What is the x402 ecosystem asking for right now?" — watched public endpoints with protocol and sign verdicts, plus recorded changes |
26
38
  | `verify_arbitrage` | $0.05 | "Is this cross-venue arbitrage opportunity real, right now?" |
27
39
  | `check_token_safety` | $0.10 | "Is this token sellable at a realistic size, and what does the round trip cost?" — TRUST / CAUTION / AVOID with evidence; not a code audit |
28
40
  | `get_best_route` | $0.03 | "What would the chain actually pay for this swap?" — best route + every quoted venue |
29
41
  | `verify_quote_fairness` | $0.05 | "A broker/bot offered me this number — is it honest?" fair / overpaying / too_good_to_be_true |
30
42
  | `get_trade_depth` | $0.05 | "How big can I trade here before the round trip eats me?" — per-size impact, round-trip cost, capacity |
31
43
 
32
- `preflight_gate` is the front door. Call it before signing any crypto
44
+ `preflight_gate` is the front door. `inspect_402` reads a 402 challenge
45
+ before an agent pays it, and `directory_402` lists the endpoints we watch.
46
+ Call the gate before signing any crypto
33
47
  transaction or x402 payment request. If `sign_allowed` is false, **do not
34
48
  sign**. If `requires_ack` is true, surface the reasons to the operator. The
35
49
  receipt expires (default 90s); call again instead of reusing it.
package/index.mjs CHANGED
@@ -8,7 +8,7 @@
8
8
  //
9
9
  // ARCHITECTURE (per docs.x402.org/guides/mcp-server-with-x402):
10
10
  //
11
- // MCP client ──▶ this bridge (MCP server + x402 payer) ──▶ verify402.com
11
+ // MCP client ──▶ this bridge (MCP server + x402 payer) ──▶ verify402.onrender.com
12
12
  //
13
13
  // 1. tool call 3. 402 + PAYMENT-REQUIRED
14
14
  // 2. paid GET/POST 4. sign payment (wallet in env)
@@ -57,6 +57,25 @@ const SERVER_URL = (process.env.VERIFY402_URL || "https://verify402.onrender.com
57
57
  // two clients separate means a misconfigured 402 on a free route can never
58
58
  // turn into a signature.
59
59
  const freeApi = axios.create({ baseURL: SERVER_URL, timeout: 30_000, maxRedirects: 0, headers: CLIENT_HEADERS });
60
+
61
+ // Anonymous usage telemetry, strictly opt-in (VERIFY402_TELEMETRY=1). One
62
+ // fire-and-forget line per tool call: the tool name and whether it worked.
63
+ // No arguments, no intent, no result, no wallet. A ping failure never blocks
64
+ // or changes the tool's answer, and the bridge never pings when it is off.
65
+ const TELEMETRY_ENABLED = process.env.VERIFY402_TELEMETRY === "1";
66
+
67
+ // Fire-and-forget. Exported for tests; the tool handlers call it positionally.
68
+ export function pingUsage(tool, ok, deps = {}) {
69
+ if (!TELEMETRY_ENABLED) return false;
70
+ const post = deps.post ?? ((body) => freeApi.post("/usage/ping", body, { timeout: 3000 }).catch(() => {}));
71
+ try {
72
+ const result = post({ tool, ok: Boolean(ok) });
73
+ if (result && typeof result.then === "function") result.catch(() => {});
74
+ return true;
75
+ } catch {
76
+ return false;
77
+ }
78
+ }
60
79
  // Spend guard: the payer refuses to SIGN any payment above this, before a
61
80
  // signature exists. Enforced by the pre-signature guard in payment-policy.mjs
62
81
  // (validatePaymentChallenge), not by request code - so it cannot be bypassed
@@ -117,7 +136,7 @@ Environment:
117
136
  VERIFY402_PAY_TO EVM payee the 402 must name (default the verify402 payee)
118
137
  VERIFY402_RESOURCE_PREFIX resource origin/prefix the 402 must match (default VERIFY402_URL)
119
138
 
120
- The free gate is preflight_gate. The paid tools are verify_arbitrage,
139
+ The free tools are preflight_gate, inspect_402 and directory_402. The paid tools are verify_arbitrage,
121
140
  check_token_safety, get_best_route, verify_quote_fairness and get_trade_depth.
122
141
  The bridge signs x402 payments only; it never signs or sends a trade.
123
142
  `);
@@ -224,6 +243,17 @@ const DESCRIPTIONS = {
224
243
  "Optional caller-supplied checks: policy.sellerPayoutWallets is a payout allowlist, not provenance; " +
225
244
  "policy.sellerPayoutManifest fetches a seller-signed manifest from a caller-pinned HTTPS origin and is the only source of payee_payout_binding; " +
226
245
  "policy.obligation checks a local settled-key ledger and cumulative spend against a grant. The gate does not persist either state.",
246
+ inspect_402:
247
+ "Read an x402 402 challenge BEFORE paying it. Pass a public endpoint URL (or the challenge you already have) " +
248
+ "and get back the price, token, network, payee, the bound resource, and a PASS / CAUTION / BLOCK verdict " +
249
+ "with typed reasons and a receipt. Use this when an agent is about to pay a server you do not control. " +
250
+ "The service fetches the challenge once, read-only: it never signs, pays, or settles. " +
251
+ "A recognized dollar stable (USDC, USDT, DAI, USDG) is named; a volatile asset gets a caution because it " +
252
+ "cannot be priced in USD. Free.",
253
+ directory_402:
254
+ "List the public x402 endpoints verify402 watches, with the price, network, payee, a protocol verdict " +
255
+ "(is the challenge well-formed?) and a sign verdict (should an agent sign it?), plus any changes " +
256
+ "since the previous check. Use it to see what the ecosystem is asking for before wiring an agent to it. Free.",
227
257
  verify_arbitrage:
228
258
  "Ask verify402 whether a cross-venue arbitrage opportunity is REAL, right now. " +
229
259
  "Quotes come from Uniswap's canonical QuoterV2 and each DEX router at one pinned block. " +
@@ -321,8 +351,10 @@ async function main() {
321
351
  };
322
352
  try {
323
353
  const res = await freeApi.post("/preflight", payload);
354
+ pingUsage("preflight_gate", true);
324
355
  return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
325
356
  } catch (e) {
357
+ pingUsage("preflight_gate", false);
326
358
  const status = e.response?.status;
327
359
  const body = e.response?.data;
328
360
  return {
@@ -340,6 +372,68 @@ async function main() {
340
372
  },
341
373
  );
342
374
 
375
+ server.tool(
376
+ "inspect_402",
377
+ DESCRIPTIONS.inspect_402,
378
+ {
379
+ url: z.string().optional().describe("Public http(s) endpoint that answers with an x402 402 challenge. Only public hosts are fetched; localhost and private ranges are refused."),
380
+ method: z.enum(["GET", "POST"]).optional().describe("HTTP method for the probe (default GET). A POST sends an empty {} body."),
381
+ challenge: z.record(z.string(), z.unknown()).optional().describe("A 402 challenge you already have. Makes no request."),
382
+ header: z.string().optional().describe("The base64 PAYMENT-REQUIRED header value. Makes no request."),
383
+ target: z.string().optional().describe("The URL the challenge belongs to. Binds the challenge's resource so the verdict can check it."),
384
+ },
385
+ async (args) => {
386
+ const payload = {
387
+ url: args.url,
388
+ method: args.method,
389
+ challenge: args.challenge,
390
+ header: args.header,
391
+ target: args.target,
392
+ };
393
+ try {
394
+ const res = await freeApi.post("/inspect", payload);
395
+ pingUsage("inspect_402", true);
396
+ return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
397
+ } catch (e) {
398
+ pingUsage("inspect_402", false);
399
+ const status = e.response?.status;
400
+ const body = e.response?.data;
401
+ return {
402
+ isError: true,
403
+ content: [{
404
+ type: "text",
405
+ text: `inspect failed${status ? ` (${status})` : ""}: ${JSON.stringify(body ?? e.message)}. ` +
406
+ "No payment was attempted and nothing was signed.",
407
+ }],
408
+ };
409
+ }
410
+ },
411
+ );
412
+
413
+ server.tool(
414
+ "directory_402",
415
+ DESCRIPTIONS.directory_402,
416
+ {},
417
+ async () => {
418
+ try {
419
+ const res = await freeApi.get("/directory.json");
420
+ pingUsage("directory_402", true);
421
+ return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
422
+ } catch (e) {
423
+ pingUsage("directory_402", false);
424
+ const status = e.response?.status;
425
+ const body = e.response?.data;
426
+ return {
427
+ isError: true,
428
+ content: [{
429
+ type: "text",
430
+ text: `directory failed${status ? ` (${status})` : ""}: ${JSON.stringify(body ?? e.message)}.`,
431
+ }],
432
+ };
433
+ }
434
+ },
435
+ );
436
+
343
437
  // Paid tools require a wallet. Without EVM_PRIVATE_KEY the server still
344
438
  // exposes the free gate, so "install it and try it" never asks for a key.
345
439
  if (paidApi) {
@@ -353,7 +447,9 @@ async function main() {
353
447
  size: z.number().optional().describe("Trade size in whole base units, e.g. 100000 (default 100000)"),
354
448
  },
355
449
  async (args) => {
356
- const res = await runPaidTool({
450
+ let res;
451
+ try {
452
+ res = await runPaidTool({
357
453
  tool: "verify_arbitrage",
358
454
  client: paidApi,
359
455
  body: {
@@ -363,6 +459,11 @@ async function main() {
363
459
  size: args.size ?? 100000,
364
460
  },
365
461
  });
462
+ pingUsage("verify_arbitrage", true);
463
+ } catch (err) {
464
+ pingUsage("verify_arbitrage", false);
465
+ throw err;
466
+ }
366
467
  return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
367
468
  },
368
469
  );
@@ -377,7 +478,9 @@ async function main() {
377
478
  offeredPriceUsd: z.number().optional().describe("Optional price per token someone offered you"),
378
479
  },
379
480
  async (args) => {
380
- const res = await runPaidTool({
481
+ let res;
482
+ try {
483
+ res = await runPaidTool({
381
484
  tool: "check_token_safety",
382
485
  client: paidApi,
383
486
  body: {
@@ -387,6 +490,11 @@ async function main() {
387
490
  offeredPriceUsd: args.offeredPriceUsd ?? null,
388
491
  },
389
492
  });
493
+ pingUsage("check_token_safety", true);
494
+ } catch (err) {
495
+ pingUsage("check_token_safety", false);
496
+ throw err;
497
+ }
390
498
  return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
391
499
  },
392
500
  );
@@ -401,7 +509,9 @@ async function main() {
401
509
  chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
402
510
  },
403
511
  async (args) => {
404
- const res = await runPaidTool({
512
+ let res;
513
+ try {
514
+ res = await runPaidTool({
405
515
  tool: "get_best_route",
406
516
  client: paidApi,
407
517
  body: {
@@ -411,6 +521,11 @@ async function main() {
411
521
  amountIn: args.amountIn,
412
522
  },
413
523
  });
524
+ pingUsage("get_best_route", true);
525
+ } catch (err) {
526
+ pingUsage("get_best_route", false);
527
+ throw err;
528
+ }
414
529
  return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
415
530
  },
416
531
  );
@@ -427,7 +542,9 @@ async function main() {
427
542
  chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
428
543
  },
429
544
  async (args) => {
430
- const res = await runPaidTool({
545
+ let res;
546
+ try {
547
+ res = await runPaidTool({
431
548
  tool: "verify_quote_fairness",
432
549
  client: paidApi,
433
550
  body: {
@@ -439,6 +556,11 @@ async function main() {
439
556
  venueClaimed: args.venueClaimed ?? null,
440
557
  },
441
558
  });
559
+ pingUsage("verify_quote_fairness", true);
560
+ } catch (err) {
561
+ pingUsage("verify_quote_fairness", false);
562
+ throw err;
563
+ }
442
564
  return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
443
565
  },
444
566
  );
@@ -454,7 +576,9 @@ async function main() {
454
576
  maxRoundTripPct: z.number().optional().describe("Your round-trip cost tolerance, default 1%"),
455
577
  },
456
578
  async (args) => {
457
- const res = await runPaidTool({
579
+ let res;
580
+ try {
581
+ res = await runPaidTool({
458
582
  tool: "get_trade_depth",
459
583
  client: paidApi,
460
584
  body: {
@@ -465,6 +589,11 @@ async function main() {
465
589
  maxRoundTripPct: args.maxRoundTripPct ?? 1.0,
466
590
  },
467
591
  });
592
+ pingUsage("get_trade_depth", true);
593
+ } catch (err) {
594
+ pingUsage("get_trade_depth", false);
595
+ throw err;
596
+ }
468
597
  return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
469
598
  },
470
599
  );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "verify402-mcp",
3
- "version": "1.0.9",
3
+ "version": "1.1.1",
4
4
  "mcpName": "io.github.a32116150-ctrl/verify402-mcp",
5
5
  "description": "MCP server for verify402: a free, fail-closed preflight gate before signing, plus five paid on-chain checks paid per call via x402.",
6
6
  "type": "module",