verify402-mcp 1.0.9 → 1.1.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/.env.example +6 -0
- package/README.md +15 -1
- package/index.mjs +135 -6
- package/package.json +1 -1
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.
|
|
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
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
3
|
+
"version": "1.1.0",
|
|
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",
|