verify402-mcp 0.0.0-stage → 1.0.2

package/.env.example

@@ -0,0 +1,20 @@
+# Bridge configuration.
+#
+# The bridge runs without any of these. With no EVM_PRIVATE_KEY it exposes only
+# the free preflight_gate. Set a key only when you want the five paid checks.
+#
+# EVM_PRIVATE_KEY is a dedicated hot wallet that pays for calls in USDC. Use a
+# wallet with only the money you are willing to spend. NEVER commit the real
+# .env and never use a main wallet.
+EVM_PRIVATE_KEY=           # optional; omit for the free gate only
+VERIFY402_URL=https://verify402.onrender.com
+# spend controls (paid tools only)
+MAX_PAYMENT_USD=0.25      # cap on ONE payment, enforced at signature time
+MAX_DAILY_USD=0.50        # cap on the whole UTC day, survives restarts; omit to disable
+SPEND_LEDGER_PATH=        # optional override for the ledger file (default .spend-ledger.json)
+
+# payment allowlist (paid tools only; these are the defaults)
+VERIFY402_NETWORKS=eip155:8453
+VERIFY402_PAY_TO=0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb
+# VERIFY402_RESOURCE_PREFIX=https://verify402.onrender.com
+# For local testnet, set VERIFY402_NETWORKS=eip155:84532 and the payee the local server names.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,8 @@
+verify402
+Copyright 2026 verify402 (https://github.com/a32116150-ctrl/verify402)
+
+This product includes software developed by the verify402 project.
+
+The verify402 name and logo identify this project. They are not licensed for
+use as trademarks to endorse or promote derived products, except as allowed by
+Section 6 of the Apache License, Version 2.0.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# verify402-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for **verify402**: a free, fail-closed **preflight gate** before an
+agent signs a payment or a chain transaction, plus five paid on-chain checks
+paid per call over x402.
+
+Works with Claude Desktop, Cursor, OpenCode, and any MCP client that speaks
+stdio. The free gate needs **no wallet**. The paid tools use a dedicated hot
+wallet that pays in USDC; the bridge never signs or sends a trade.
+
+## Tools
+
+| tool | price | what it answers |
+|---|---|---|
+| `preflight_gate` | **free** | "Should I sign this payment request or transaction?" — PASS / CAUTION / BLOCK with reasons, `checked` / `notChecked`, and a short-lived receipt |
+| `verify_arbitrage` | $0.05 | "Is this cross-venue arbitrage opportunity real, right now?" |
+| `check_token_safety` | $0.10 | "Is this token safe to buy?" — TRUST / CAUTION / AVOID with evidence |
+| `get_best_route` | $0.03 | "What would the chain actually pay for this swap?" — best route + every quoted venue |
+| `verify_quote_fairness` | $0.05 | "A broker/bot offered me this number — is it honest?" fair / overpaying / too_good_to_be_true |
+| `get_trade_depth` | $0.05 | "How big can I trade here before the round trip eats me?" — per-size impact, round-trip cost, capacity |
+
+`preflight_gate` is the front door. Call it before signing any crypto
+transaction or x402 payment request. If `sign_allowed` is false, **do not
+sign**. If `requires_ack` is true, surface the reasons to the operator. The
+receipt expires (default 90s); call again instead of reusing it.
+
+The gate is advisory at this layer: the bridge does not hold the agent's
+transaction key and cannot stop an agent that ignores the answer. Enforcement
+belongs in the executor that signs — verify the receipt, then sign. See
+[`examples/preflight-guard.mjs`](https://github.com/a32116150-ctrl/verify402/blob/master/examples/preflight-guard.mjs)
+for a deny-by-default reference that refuses to call the signer without a
+verified receipt.
+
+## Run
+
+The package is distributed as a versioned GitHub release tarball. No npm
+account is required.
+
+```bash
+npx -y \
+  --package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz \
+  verify402-mcp --help
+```
+
+**Warm the cache first.** The first `npx` run installs the MCP SDK and `viem`;
+some clients kill a server that takes more than 30 seconds to start. Run the
+`--help` command once before adding it to an MCP client. After that, startup is
+fast.
+
+From source:
+
+```bash
+git clone https://github.com/a32116150-ctrl/verify402
+cd verify402/mcp-bridge
+npm ci
+node index.mjs --help
+```
+
+## Free gate only (no key)
+
+Omit `EVM_PRIVATE_KEY`. The server registers only `preflight_gate` and logs
+`free preflight_gate only`. Nothing can be charged.
+
+## Paid tools (dedicated hot wallet)
+
+Set a wallet with USDC on the payment network. Use a wallet with only the money
+you are willing to spend — never a main wallet. The key stays in your MCP client
+configuration or environment; the package never contains it.
+
+```
+EVM_PRIVATE_KEY=0x...        # optional; omit for free-only
+VERIFY402_URL=https://verify402.onrender.com
+MAX_PAYMENT_USD=0.25         # hard cap on ONE payment, enforced at signature time
+MAX_DAILY_USD=0.50           # optional cap for the UTC day, persisted
+SPEND_LEDGER_PATH=           # optional ledger path (default .spend-ledger.json)
+VERIFY402_NETWORKS=eip155:8453   # paid calls only; comma-separated EVM networks
+VERIFY402_PAY_TO=0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb
+# VERIFY402_RESOURCE_PREFIX=https://verify402.onrender.com
+```
+
+The paid client refuses a 402 that names another network or payee, a resource
+outside the configured server, or a non-paid route. It also refuses redirects.
+The amount cap and the USDC-only default-asset allowlist are enforced inside
+the x402 client, before a signature exists.
+
+### Claude Desktop / Cursor
+
+`claude_desktop_config.json`, or `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "verify402": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz",
+        "verify402-mcp"
+      ],
+      "env": {
+        "VERIFY402_URL": "https://verify402.onrender.com"
+      }
+    }
+  }
+}
+```
+
+For paid tools, add `"EVM_PRIVATE_KEY": "0x..."`, `"MAX_PAYMENT_USD": "0.25"`
+and optionally `"MAX_DAILY_USD": "0.50"` to `env`. The free gate works without
+them.
+
+### OpenCode V2
+
+`opencode.jsonc`, or the global `~/.config/opencode/opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "verify402": {
+        "type": "local",
+        "command": [
+          "npx",
+          "-y",
+          "--package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz",
+          "verify402-mcp"
+        ],
+        "environment": {
+          "VERIFY402_URL": "https://verify402.onrender.com"
+        }
+      }
+    }
+  }
+}
+```
+
+For paid tools, add `"EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}"` to
+`environment` and export the key in the environment that starts OpenCode. Keep
+the secret out of the config file.
+
+## Safety
+
+- The bridge signs **x402 payments only**. It never signs or broadcasts a trade.
+- Before signing, the paid client requires the 402 to come from the configured
+  server and a known paid route, on an allowlisted EVM network, to the
+  verify402 payee. It accepts only recognized default assets (USDC), caps the
+  amount at `MAX_PAYMENT_USD`, and refuses redirects.
+- The allowlist can be narrowed or pointed at another deployment with
+  `VERIFY402_NETWORKS`, `VERIFY402_PAY_TO`, and `VERIFY402_RESOURCE_PREFIX`.
+  Defaults are Base mainnet and the public verify402 payee.
+- `MAX_PAYMENT_USD` is enforced inside the x402 client, before a signature
+  exists; removing it is a security regression.
+- `preflight_gate` is a check, not a guarantee. Read `notChecked`: it does not
+  screen recipient reputation or sanctions, audit contracts, simulate full
+  balance deltas, or protect against MEV. It catches the measurable signing
+  mistakes, not every scam.
+- Use the [reference executor](https://github.com/a32116150-ctrl/verify402/blob/master/examples/preflight-guard.mjs)
+  when you want enforcement rather than advice.
+
+## Development
+
+```bash
+npm pack --dry-run
+```
+
+## License
+
+Apache License 2.0. See `LICENSE` and `NOTICE`.
+
+You may use, modify, and distribute this package, including in commercial agent
+systems and bots. If you redistribute it or a product containing it, keep the
+copyright notice, the license text, and the `NOTICE` file. The `verify402` name
+and logo are not licensed for endorsement.

package/budget.mjs

@@ -0,0 +1,65 @@
+// Per-day client-side budget for the verify402 MCP bridge.
+//
+// MAX_PAYMENT_USD caps ONE payment. That answered "how much can one talked-
+//into prompt drain?" but an operator on MoltJobs (vegachiefofstaff) asked the
+// sharper question and was right: nothing stopped a long-running task from
+// opening a fresh client and resetting the cap. This module adds the missing
+// layer, enforced client-side with a persisted ledger:
+//
+//   MAX_DAILY_USD (optional, off by default) caps the TOTAL spent per UTC day,
+//   across process restarts, via a small JSON ledger file. A attempted charge
+//   is recorded BEFORE the payment is constructed: for a spending guard the
+//   conservative direction is to over-count, never to under-count.
+//
+// Disabled when MAX_DAILY_USD is unset/0 — the bridge then behaves exactly as
+// before, which is also what pure-local testing wants.
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+export const DEFAULT_PRICES = {
+  "/verify": 0.05,
+  "/safety": 0.10,
+  "/route": 0.03,
+  "/quotecheck": 0.05,
+  "/depth": 0.05,
+};
+
+const dayKey = () => new Date().toISOString().slice(0, 10);
+
+function loadLedger(file) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (typeof j.totalUsd === "number" && j.day === dayKey()) return j;
+  } catch { /* fresh day or fresh file */ }
+  return { day: dayKey(), totalUsd: 0 };
+}
+
+export function createDailyBudget({ maxDailyUsd, ledgerPath, pricesOverride } = {}) {
+  const cap = Number(maxDailyUsd || 0);
+  if (!(cap > 0)) return { enabled: false, assert: () => ({ charged: 0, totalUsd: null, remaining: null }) };
+
+  const file = ledgerPath || path.join(path.dirname(fileURLToPath(import.meta.url)), ".spend-ledger.json");
+  const prices = { ...DEFAULT_PRICES, ...(pricesOverride || {}) };
+
+  function assert(route) {
+    let price = prices[route];
+    if (price == null) price = prices.default ?? 0;
+    const ledger = loadLedger(file);
+    const next = Math.round((ledger.totalUsd + price) * 1e6) / 1e6;
+    if (next > cap + 1e-9) {
+      throw new Error(
+        `daily budget exhausted: $${ledger.totalUsd} of $${cap} spent today; refusing ${route} ($${price}). ` +
+        `Raise MAX_DAILY_USD in the bridge .env or wait for the next UTC day.`,
+      );
+    }
+    ledger.totalUsd = next;
+    ledger.lastRoute = route;
+    ledger.lastAt = new Date().toISOString();
+    fs.writeFileSync(file, JSON.stringify(ledger, null, 2));
+    return { charged: price, totalUsd: next, remaining: Math.max(0, cap - next) };
+  }
+
+  return { enabled: true, cap, file, assert };
+}

package/index.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+// verify402 MCP bridge.
+//
+// Makes verify402 consumable by any MCP client (Claude Desktop, OpenCode, any
+// agent framework) as native tools. The free preflight gate works with no
+// wallet. The five paid checks use an x402 payment handshake from the wallet in
+// EVM_PRIVATE_KEY and return the verdict.
+//
+// ARCHITECTURE (per docs.x402.org/guides/mcp-server-with-x402):
+//
+//   MCP client ──▶ this bridge (MCP server + x402 payer) ──▶ verify402.com
+//
+//   1. tool call            3. 402 + PAYMENT-REQUIRED
+//   2. paid GET/POST        4. sign payment (wallet in env)
+//                           5. retry with proof → verdict
+//
+// PAYMENT POLICY (load-bearing, do not remove): before a signature exists,
+// x402Client's spend controls enforce the USD cap and the default-asset
+// (USDC) allowlist; payment-policy.mjs then enforces the network allowlist,
+// the verify402 payee, and a known paid resource on the configured server.
+// Redirects are refused. An MCP server that signs anything any remote 402
+// asks for is a blank cheque. This one is not.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import axios from "axios";
+import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+import { config } from "dotenv";
+import { z } from "zod";
+
+config();
+
+const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;
+const SERVER_URL = process.env.VERIFY402_URL || "https://verify402.onrender.com";
+// Preflight is free, so it does not go through the paying client. Keeping the
+// two clients separate means a misconfigured 402 on a free route can never
+// turn into a signature.
+const freeApi = axios.create({ baseURL: SERVER_URL, timeout: 30_000, maxRedirects: 0 });
+// Spend guard: the x402 client refuses to SIGN any payment above this, before
+// a signature exists. Enforced inside x402Client (applySpendControls), not by
+// our own request code - so it cannot be bypassed by a caller.
+const MAX_PAYMENT_USD = Number(process.env.MAX_PAYMENT_USD || 0.25);
+
+// Free-only mode is deliberate: an agent can install the bridge and call the
+// free preflight gate without handing it a private key. The paid tools are
+// registered only when a wallet is configured.
+const PAID_ENABLED = Boolean(EVM_PRIVATE_KEY);
+
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`verify402-mcp — MCP server for verify402
+
+Usage:
+  verify402-mcp                 start the stdio MCP server
+  verify402-mcp --help          show this help
+  verify402-mcp --version       print the version
+
+Environment:
+  VERIFY402_URL     verify402 base URL (default https://verify402.onrender.com)
+  EVM_PRIVATE_KEY   optional; omit for the free preflight_gate only
+  MAX_PAYMENT_USD   cap on one x402 payment (default 0.25)
+  MAX_DAILY_USD     optional cap for the UTC day, persisted in a small ledger
+  SPEND_LEDGER_PATH optional ledger path (default .spend-ledger.json)
+  VERIFY402_NETWORKS  comma-separated EVM networks for paid calls (default eip155:8453)
+  VERIFY402_PAY_TO    EVM payee the 402 must name (default the verify402 payee)
+  VERIFY402_RESOURCE_PREFIX  resource origin/prefix the 402 must match (default VERIFY402_URL)
+
+The free gate is preflight_gate. The paid tools are verify_arbitrage,
+check_token_safety, get_best_route, verify_quote_fairness and get_trade_depth.
+The bridge signs x402 payments only; it never signs or sends a trade.
+`);
+  process.exit(0);
+}
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+  console.log("1.0.2");
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------- payment ---
+async function createPaidClient() {
+  if (!Number.isFinite(MAX_PAYMENT_USD) || MAX_PAYMENT_USD <= 0) {
+    throw new Error("MAX_PAYMENT_USD must be a positive number");
+  }
+  const policy = createPaymentPolicy({
+    networks: process.env.VERIFY402_NETWORKS || DEFAULT_NETWORKS,
+    payTo: process.env.VERIFY402_PAY_TO || DEFAULT_PAY_TO,
+    resourcePrefix: process.env.VERIFY402_RESOURCE_PREFIX || SERVER_URL,
+    paidRoutes: Object.keys(DEFAULT_PRICES),
+  });
+  const account = privateKeyToAccount(EVM_PRIVATE_KEY);
+  const client = x402Client.fromConfig({
+    schemes: [], // registered below, one per allowlisted network
+    spendControls: { maxAmountPerPayment: `$${MAX_PAYMENT_USD}` },
+    policies: [(version, requirements) => policy.filter(version, requirements)],
+  });
+  for (const network of policy.allowedNetworks) {
+    client.register(network, new ExactEvmScheme(account));
+  }
+  client.onBeforePaymentCreation((context) => policy.checkBeforeSign(context));
+  console.error(
+    `paid policy: networks=${policy.allowedNetworks.join(",")} ` +
+      `payee=${policy.allowedPayTo} resources=${policy.resourcePrefix} ` +
+      `{${policy.paidRoutes.join(",")}}`,
+  );
+  const axiosInstance = axios.create({ baseURL: SERVER_URL, timeout: 120_000, maxRedirects: 0 });
+  return wrapAxiosWithPayment(axiosInstance, client);
+}
+
+// ------------------------------------------------------------------ budget --
+// The second, broader guard: MAX_PAYMENT_USD caps ONE payment; MAX_DAILY_USD
+// (optional) caps the whole UTC day across restarts, persisted in a tiny
+// ledger file. Attempted charges are counted conservatively (before payment).
+import { createDailyBudget, DEFAULT_PRICES } from "./budget.mjs";
+import { createPaymentPolicy, DEFAULT_NETWORKS, DEFAULT_PAY_TO } from "./payment-policy.mjs";
+const dailyBudget = createDailyBudget({
+  maxDailyUsd: process.env.MAX_DAILY_USD,
+});
+
+async function guardedPaidCall(route, run) {
+  if (dailyBudget.enabled) dailyBudget.assert(route);
+  return run();
+}
+
+// ------------------------------------------------------------------ tools ---
+const DESCRIPTIONS = {
+  preflight_gate:
+    "Call this BEFORE signing any crypto transaction or x402 payment request. " +
+    "Returns PASS / CAUTION / BLOCK with typed reasons, the checks that actually ran, " +
+    "the checks that did not, and a short-lived receipt bound to the exact intent + block. " +
+    "If sign_allowed is false, DO NOT SIGN. If requires_ack is true, surface the reasons to the " +
+    "operator before signing. The receipt expires (default 90s): call again rather than reuse it. " +
+    "Free. Pass `from` (the wallet that will sign) to enable simulation and balance checks.",
+  verify_arbitrage:
+    "Ask verify402 whether a cross-venue arbitrage opportunity is REAL, right now. " +
+    "Quotes come from Uniswap's canonical QuoterV2 and each DEX router at one pinned block. " +
+    "The honest answer is usually 'no_edge' - that IS the product. Costs $0.05 per call.",
+  check_token_safety:
+    "Ask verify402 whether a token is safe to buy BEFORE the agent risks capital. " +
+    "Returns TRUST/CAUTION/AVOID with evidence: live contract facts, market liquidity, " +
+    "a USD-sized sell probe against every venue (honeypot test), round-trip cost at your " +
+    "intended size, and phantom-price detection. Costs $0.10 per call.",
+  get_best_route:
+    "Ask verify402 what the chain would ACTUALLY pay for a swap: the full execution book " +
+    "(every venue, direct and WETH-routed) at one pinned block, best first. Costs $0.03 per call.",
+  verify_quote_fairness:
+    "Audit a swap quote someone else gave you (aggregator, broker, bot) BEFORE signing. " +
+    "Returns fair / overpaying / too_good_to_be_true with the full chain book as evidence. " +
+    "Ask this before accepting ANY number you did not produce yourself. Costs $0.05 per call.",
+  get_trade_depth:
+    "Position sizing: measure how much of a token the chain ACTUALLY lets you trade - " +
+    "entry and exit across every venue at a ladder of USD sizes, per-size impact and " +
+    "round-trip cost, plus the largest size under your cost tolerance. Ask BEFORE choosing " +
+    "a position size. Costs $0.05 per call.",
+};
+
+async function main() {
+  const paidApi = PAID_ENABLED ? await createPaidClient() : null;
+
+  const server = new McpServer({ name: "verify402", version: "1.0.2" });
+
+  server.tool(
+    "preflight_gate",
+    DESCRIPTIONS.preflight_gate,
+    {
+      kind: z.enum(["payment", "transaction"]).describe("payment = an x402 402 challenge; transaction = a chain transaction"),
+      chainId: z.number().optional().describe("EVM chain id: 1 Ethereum, 42161 Arbitrum, 8453 Base. For payment, cross-checks the network."),
+      from: z.string().optional().describe("The wallet that will sign. Strongly recommended: enables simulation and balance checks."),
+      payment: z.object({
+        scheme: z.string().optional().describe('x402 scheme, normally "exact"'),
+        network: z.string().describe('CAIP-2 network, e.g. "eip155:8453" or "solana:..."'),
+        asset: z.string().describe("Token address or mint, e.g. canonical USDC on that network"),
+        amount: z.string().describe("RAW amount in the asset's smallest unit, as a string"),
+        payTo: z.string().describe("Recipient address from the 402 challenge"),
+        resource: z.string().optional().describe("The resource URL the payment is for"),
+        maxTimeoutSeconds: z.number().optional().describe("maxTimeoutSeconds from the 402 challenge"),
+        extra: z.object({
+          validAfter: z.number().optional(),
+          validBefore: z.number().optional(),
+          facilitator: z.string().optional(),
+        }).optional().describe("x402 extra fields: validAfter / validBefore / facilitator"),
+      }).optional().describe("Required when kind=payment"),
+      to: z.string().optional().describe("Transaction target (required when kind=transaction)"),
+      data: z.string().optional().describe("0x calldata for the transaction"),
+      value: z.string().optional().describe("Native value in wei, as a decimal string"),
+      policy: z.object({
+        maxAmountUsd: z.number().optional().describe("Reject payments above this USD value"),
+        maxValueWei: z.string().optional().describe("Reject native value above this wei amount"),
+        maxValueEth: z.number().optional().describe("Reject native value above this ETH amount"),
+        allowedNetworks: z.array(z.string()).optional().describe("Allowlist of CAIP-2 networks"),
+        allowedPayTo: z.array(z.string()).optional().describe("Allowlist of payment recipients"),
+        allowedTo: z.array(z.string()).optional().describe("Allowlist of transaction targets"),
+        allowedSpenders: z.array(z.string()).optional().describe("Allowlist of approval spenders"),
+        allowedAssets: z.array(z.string()).optional().describe("Allowlist of payment assets"),
+        allowedFacilitators: z.array(z.string()).optional().describe("Allowlist of x402 facilitators"),
+        expectedResource: z.string().optional().describe("The exact resource URL the agent intends to pay for"),
+        forbidUnlimitedApproval: z.boolean().optional().describe("Turn an unlimited approve into a BLOCK"),
+        maxTimeoutSeconds: z.number().optional().describe("Reject challenges with a longer timeout"),
+      }).optional().describe("Operator policy. Omit for structural checks only."),
+      ttlSeconds: z.number().optional().describe("Receipt lifetime in seconds, 15-300 (default 90)"),
+    },
+    async (args) => {
+      const payload = {
+        kind: args.kind,
+        chainId: args.chainId,
+        from: args.from,
+        payment: args.payment,
+        to: args.to,
+        data: args.data,
+        value: args.value,
+        policy: args.policy,
+        ttlSeconds: args.ttlSeconds,
+      };
+      try {
+        const res = await freeApi.post("/preflight", payload);
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+      } catch (e) {
+        const status = e.response?.status;
+        const body = e.response?.data;
+        return {
+          isError: true,
+          content: [{
+            type: "text",
+            text: `preflight failed${status ? ` (${status})` : ""}: ${JSON.stringify(body ?? e.message)}. Do not sign without a verifiable receipt.`,
+          }],
+        };
+      }
+    },
+  );
+
+  // Paid tools require a wallet. Without EVM_PRIVATE_KEY the server still
+  // exposes the free gate, so "install it and try it" never asks for a key.
+  if (paidApi) {
+  server.tool(
+    "verify_arbitrage",
+    DESCRIPTIONS.verify_arbitrage,
+    {
+      target: z.string().describe('Token to buy and sell back, e.g. "WETH"'),
+      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+      base: z.string().optional().describe('Token to trade from, e.g. "USDC" (default USDC)'),
+      size: z.number().optional().describe("Trade size in whole base units, e.g. 100000 (default 100000)"),
+    },
+    async (args) => {
+      const res = await guardedPaidCall("/verify", () => paidApi.post("/verify", {
+        chainId: args.chainId ?? 1,
+        target: String(args.target ?? "WETH").toUpperCase(),
+        base: String(args.base ?? "USDC").toUpperCase(),
+        size: args.size ?? 100000,
+      }));
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    },
+  );
+
+  server.tool(
+    "check_token_safety",
+    DESCRIPTIONS.check_token_safety,
+    {
+      tokenAddress: z.string().describe("ERC-20 contract address, or a known symbol like WETH"),
+      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+      intendedUsd: z.number().optional().describe("Size the agent plans to buy, in USD (default 500)"),
+      offeredPriceUsd: z.number().optional().describe("Optional price per token someone offered you"),
+    },
+    async (args) => {
+      const res = await guardedPaidCall("/safety", () => paidApi.post("/safety", {
+        chainId: args.chainId ?? 1,
+        tokenAddress: String(args.tokenAddress ?? "").trim(),
+        intendedUsd: args.intendedUsd ?? 500,
+        offeredPriceUsd: args.offeredPriceUsd ?? null,
+      }));
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    },
+  );
+
+  server.tool(
+    "get_best_route",
+    DESCRIPTIONS.get_best_route,
+    {
+      tokenIn: z.string().describe("Token symbol (e.g. USDC) or 0x address"),
+      tokenOut: z.string().describe("Token symbol (e.g. WETH) or 0x address"),
+      amountIn: z.string().describe("RAW base units of tokenIn, wei-scale, as a string"),
+      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+    },
+    async (args) => {
+      const res = await guardedPaidCall("/route", () => paidApi.post("/route", {
+        chainId: args.chainId ?? 1,
+        tokenIn: args.tokenIn,
+        tokenOut: args.tokenOut,
+        amountIn: args.amountIn,
+      }));
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    },
+  );
+
+  server.tool(
+    "verify_quote_fairness",
+    DESCRIPTIONS.verify_quote_fairness,
+    {
+      tokenIn: z.string().describe("Token you are selling (symbol or 0x address)"),
+      tokenOut: z.string().describe("Token you would receive (symbol or 0x address)"),
+      amountIn: z.string().describe("RAW units of tokenIn, as in the offer"),
+      quotedOut: z.string().describe("RAW units of tokenOut you were OFFERED"),
+      venueClaimed: z.string().optional().describe("Optional: who gave you the offer"),
+      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+    },
+    async (args) => {
+      const res = await guardedPaidCall("/quotecheck", () => paidApi.post("/quotecheck", {
+        chainId: args.chainId ?? 1,
+        tokenIn: args.tokenIn,
+        tokenOut: args.tokenOut,
+        amountIn: args.amountIn,
+        quotedOut: args.quotedOut,
+        venueClaimed: args.venueClaimed ?? null,
+      }));
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    },
+  );
+
+  server.tool(
+    "get_trade_depth",
+    DESCRIPTIONS.get_trade_depth,
+    {
+      tokenAddress: z.string().describe("Token you plan to buy (symbol or 0x address)"),
+      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+      baseSymbol: z.string().optional().describe("What you pay with (default USDC)"),
+      sizesUsd: z.array(z.number()).optional().describe("Ladder of sizes in USD, max 6 (default 100, 1000, 10000, 100000)"),
+      maxRoundTripPct: z.number().optional().describe("Your round-trip cost tolerance, default 1%"),
+    },
+    async (args) => {
+      const res = await guardedPaidCall("/depth", () => paidApi.post("/depth", {
+        chainId: args.chainId ?? 1,
+        tokenAddress: args.tokenAddress,
+        baseSymbol: args.baseSymbol ?? "USDC",
+        sizesUsd: args.sizesUsd ?? null,
+        maxRoundTripPct: args.maxRoundTripPct ?? 1.0,
+      }));
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    },
+  );
+  } // end paid tools
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(
+    paidApi
+      ? `verify402 MCP bridge connected -> ${SERVER_URL} (paid tools on, max payment $${MAX_PAYMENT_USD})`
+      : `verify402 MCP bridge connected -> ${SERVER_URL} (free preflight_gate only; set EVM_PRIVATE_KEY for paid tools)`,
+  );
+}
+
+main().catch((e) => {
+  console.error("bridge failed:", e.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "verify402-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "mcpName": "io.github.a32116150-ctrl/verify402-mcp",
+  "description": "MCP server for verify402: a free, fail-closed preflight gate before signing, plus five paid on-chain checks paid per call via x402.",
+  "type": "module",
+  "bin": {
+    "verify402-mcp": "index.mjs"
+  },
+  "main": "index.mjs",
+  "files": [
+    "index.mjs",
+    "budget.mjs",
+    "payment-policy.mjs",
+    "README.md",
+    ".env.example",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "start": "node index.mjs",
+    "test": "node --test test/payment-policy.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "ai-agents",
+    "crypto",
+    "preflight",
+    "payments",
+    "base",
+    "solana",
+    "trading-bot"
+  ],
+  "license": "Apache-2.0",
+  "author": "verify402 (https://github.com/a32116150-ctrl/verify402)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a32116150-ctrl/verify402.git",
+    "directory": "mcp-bridge"
+  },
+  "homepage": "https://verify402.onrender.com/mcp",
+  "bugs": {
+    "url": "https://github.com/a32116150-ctrl/verify402/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@x402/axios": "^2.28.0",
+    "@x402/evm": "^2.28.0",
+    "axios": "^1.13.2",
+    "dotenv": "^16.4.5",
+    "viem": "^2.39.0",
+    "zod": "^4.6.7"
+  }
+}

package/payment-policy.mjs

@@ -0,0 +1,162 @@
+// Payment policy for the paid x402 client.
+//
+// The bridge is a payer, not a blank cheque for any remote 402. Before a
+// signature exists, the policy requires:
+//
+//   - the network to be explicitly allowlisted (default Base mainnet);
+//   - payTo to be the verify402 payee (default the EVM payTo);
+//   - the 402 resource to be on the configured server and a known paid route.
+//
+// The amount cap and the default-asset (USDC) allowlist are enforced by
+// x402Client's spendControls, which run before this policy. Redirects are
+// refused by the axios client in index.mjs.
+//
+// Free-only mode never imports or constructs this policy.
+
+export const DEFAULT_NETWORKS = ["eip155:8453"];
+export const DEFAULT_PAY_TO = "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb";
+export const DEFAULT_PAID_ROUTES = ["/verify", "/safety", "/route", "/quotecheck", "/depth"];
+
+function parseNetworks(raw) {
+  const values = Array.isArray(raw) ? raw : String(raw ?? "").split(",");
+  const networks = values.map((value) => String(value).trim()).filter(Boolean);
+  if (networks.length === 0) {
+    throw new Error("VERIFY402_NETWORKS must list at least one eip155:<chainId> network");
+  }
+  for (const network of networks) {
+    if (!/^eip155:\d+$/.test(network)) {
+      throw new Error(`VERIFY402_NETWORKS: ${network} is not an eip155:<chainId> network`);
+    }
+  }
+  return [...new Set(networks)];
+}
+
+function normalizePayTo(raw) {
+  const value = String(raw ?? "").trim();
+  if (!/^0x[0-9a-fA-F]{40}$/.test(value)) {
+    throw new Error("VERIFY402_PAY_TO must be a 20-byte 0x EVM address");
+  }
+  return value.toLowerCase();
+}
+
+function normalizePrefix(raw) {
+  const value = String(raw ?? "").trim().replace(/\/+$/, "");
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`VERIFY402_RESOURCE_PREFIX is not a URL: ${value || "(empty)"}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`VERIFY402_RESOURCE_PREFIX must be http(s): ${value}`);
+  }
+  return {
+    value,
+    origin: url.origin,
+    pathPrefix: url.pathname.replace(/\/+$/, ""),
+  };
+}
+
+/**
+ * Build the paid-call policy. Throws on invalid configuration so a paid-mode
+ * start fails closed instead of silently accepting a wider policy.
+ */
+export function createPaymentPolicy({
+  networks = DEFAULT_NETWORKS,
+  payTo = DEFAULT_PAY_TO,
+  resourcePrefix,
+  paidRoutes = DEFAULT_PAID_ROUTES,
+} = {}) {
+  const allowedNetworks = parseNetworks(networks);
+  const allowed = new Set(allowedNetworks);
+  const allowedPayTo = normalizePayTo(payTo);
+  const prefix = normalizePrefix(resourcePrefix);
+  const routes = new Set(paidRoutes.map(String));
+
+  return {
+    allowedNetworks,
+    allowedPayTo,
+    resourcePrefix: prefix.value,
+    paidRoutes: [...routes],
+
+    /**
+     * x402Client policy: runs after spend controls and before the selector.
+     * Returning an empty array would also fail, but a typed error is easier to
+     * debug and is surfaced to the caller as a refused payment.
+     */
+    filter(_x402Version, requirements) {
+      const passing = requirements.filter((requirement) => {
+        const network = String(requirement?.network ?? "");
+        const requirementPayTo = String(requirement?.payTo ?? "").toLowerCase();
+        return allowed.has(network) && requirementPayTo === allowedPayTo;
+      });
+      if (passing.length === 0) {
+        throw new Error(
+          `402 offered no payment on an allowed network/payee ` +
+            `(allowed networks: ${allowedNetworks.join(", ")}; payee: ${allowedPayTo})`,
+        );
+      }
+      return passing;
+    },
+
+    /**
+     * x402Client onBeforePaymentCreation hook: runs after selection and before
+     * the scheme creates a signature. Returning `{ abort: true }` fails closed.
+     */
+    checkBeforeSign(context) {
+      const rawResource = context?.paymentRequired?.resource;
+      const resourceUrl = typeof rawResource === "string" ? rawResource : rawResource?.url;
+      if (!resourceUrl) {
+        return { abort: true, reason: "402 has no resource URL" };
+      }
+
+      let url;
+      try {
+        url = new URL(String(resourceUrl));
+      } catch {
+        return { abort: true, reason: `402 resource is not a URL: ${String(resourceUrl)}` };
+      }
+
+      if (url.origin !== prefix.origin) {
+        return {
+          abort: true,
+          reason: `402 resource origin ${url.origin} is not the configured ${prefix.origin}`,
+        };
+      }
+
+      const pathOk =
+        prefix.pathPrefix === "" ||
+        url.pathname === prefix.pathPrefix ||
+        url.pathname.startsWith(`${prefix.pathPrefix}/`);
+      if (!pathOk) {
+        return {
+          abort: true,
+          reason: `402 resource ${url.href} is outside ${prefix.value}`,
+        };
+      }
+
+      if (!routes.has(url.pathname)) {
+        return {
+          abort: true,
+          reason: `402 resource path ${url.pathname} is not a paid verify402 route`,
+        };
+      }
+
+      const requirement = context?.selectedRequirements;
+      if (!requirement) {
+        return { abort: true, reason: "402 selected no payment requirement" };
+      }
+      if (
+        !allowed.has(String(requirement.network)) ||
+        String(requirement.payTo ?? "").toLowerCase() !== allowedPayTo
+      ) {
+        return {
+          abort: true,
+          reason: "selected payment requirement changed after selection",
+        };
+      }
+
+      return;
+    },
+  };
+}