verify402
Portão gratuito de pré-assinatura para agentes de negociação de IA (PASS/BLOCK mais um recibo assinado) e verificações pagas com respaldo de evidências: essa arbitragem é real, esse token é seguro, essa cotação é justa e o quanto meu tamanho pode mover.
Documentação
verify402-mcp
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 public demo's paid tools use a
dedicated hot wallet funded with Base Sepolia testnet USDC (eip155:84532).
The analysis reads mainnet chain data, but the demo never settles mainnet
payments. The bridge never signs or sends a trade.
Published package note:
verify402-mcp@1.0.9is published to npm and defaults paid calls to Base Sepolia testnet (eip155:84532) for the public demo. Base mainnet (eip155:8453) requires an explicitVERIFY402_NETWORKSopt-in in a separate deployment and is not enabled by this release. The previously published1.0.8,1.0.6,1.0.5, and1.0.4packages are immutable, and1.0.4used Base mainnet by default. Do not republish or overwrite any of them.
Anonymous usage telemetry (opt-in)
The bridge can send one anonymous line per tool call to the service: the tool
name and whether it succeeded (POST /usage/ping). Never arguments, intents,
results, wallet data, or IPs. Off by default; set VERIFY402_TELEMETRY=1 to
turn it on. A failed ping never changes the tool's answer, and only these
tool names are accepted: preflight_gate, inspect_402, directory_402,
verify_arbitrage, check_token_safety, get_best_route,
verify_quote_fairness, get_trade_depth.
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 |
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 |
directory_402 | free | "What is the x402 ecosystem asking for right now?" — watched public endpoints with protocol and sign verdicts, plus recorded changes |
verify_arbitrage | $0.05 | "Is this cross-venue arbitrage opportunity real, right now?" |
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 |
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. inspect_402 reads a 402 challenge
before an agent pays it, and directory_402 lists the endpoints we watch.
Call the gate 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.
For payment intents, policy.allowedResourceHosts binds the host in
payment.resource; a matching host can PASS and a foreign host is BLOCK.
Without allowedResourceHosts or expectedResource, an otherwise valid
resource is CAUTION resource_identity_unverified and resource identity is
listed in notChecked. The bridge forwards this policy to the server; the
server enforces it.
Two optional caller-supplied checks are forwarded as-is:
payment.idempotencyKey+policy.obligation.settledKeysrejects a key the caller already settled;policy.obligation.spentUsd+grantUsdrejects cumulative spend over the grant. The bridge does not persist this state.policy.sellerPayoutWalletsis a caller-supplied payout allowlist. A mismatch is BLOCK, but a match is not provenance and never addspayee_payout_binding.policy.sellerPayoutManifestfetches a seller-signed manifest from a caller-pinned HTTPS origin outside the 402. Only a verified manifest whosepayTolist matches addspayee_payout_binding. The response includespayeeBindingwith the source, origin, signer, expiry, and manifest hash.
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
for a deny-by-default reference that refuses to call the signer without a
verified receipt.
Distribution & Run
The package is officially published on npm as verify402-mcp and indexed on the official Model Context Protocol Registry.
Run directly via npx (stdio transport):
npx -y verify402-mcp --help
You can also install it globally:
npm install -g verify402-mcp
verify402-mcp --help
Or run from source:
git clone https://github.com/a32116150-ctrl/verify402
cd verify402/mcp-bridge
npm ci
node index.mjs --help
AI Agent Integration (Step-by-Step)
Step 1: Free Mode (Zero Config, No Wallet)
To give your AI agent the free preflight_gate (checks transaction calldata, payment challenges, payee/amount, approvals, and block freshness before signing), paste this into your client configuration. The paid check_token_safety check adds a quote-based sellability check; it does not execute a transfer and is not a honeypot guarantee.
Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):
{
"mcpServers": {
"verify402": {
"command": "npx",
"args": ["-y", "verify402-mcp"],
"env": {
"VERIFY402_URL": "https://verify402.onrender.com"
}
}
}
}
Step 2: Paid Mode (Setting Up the Hot Wallet)
To enable the 5 deep on-chain truth checks (verify_arbitrage, check_token_safety, get_best_route, verify_quote_fairness, get_trade_depth), configure a dedicated hot wallet that pays per call in USDC via x402:
- Create a Dedicated Hot Wallet:
- Create a brand new wallet in MetaMask, Rabby, or via
cast wallet new. - ⚠️ SECURITY WARNING: Never use your primary personal wallet, cold storage, or vault.
- Create a brand new wallet in MetaMask, Rabby, or via
- Fund the Wallet on Base Sepolia testnet (EIP-155:84532):
- USDC: Get Base Sepolia testnet USDC from a faucet (the bridge pays per call: $0.03 to $0.10 in testnet USDC).
- Gas (ETH on Base Sepolia): Get a small amount of Base Sepolia testnet ETH for gas if your client needs it. No mainnet funds are required for the public demo.
- Configure Environment Variables in Your MCP Client:
- Set
EVM_PRIVATE_KEYto the 64-character private key of the hot wallet. - Set
VERIFY402_NETWORKStoeip155:84532(Base Sepolia testnet). - Set safety caps
MAX_PAYMENT_USD(e.g.,"0.25") andMAX_DAILY_USD(e.g.,"1.00").
- Set
Paid Configuration Block (Claude Desktop, Cursor, Cline, Windsurf):
{
"mcpServers": {
"verify402": {
"command": "npx",
"args": ["-y", "verify402-mcp"],
"env": {
"VERIFY402_URL": "https://verify402.onrender.com",
"EVM_PRIVATE_KEY": "0xYOUR_HOT_WALLET_PRIVATE_KEY",
"MAX_PAYMENT_USD": "0.25",
"MAX_DAILY_USD": "1.00",
"VERIFY402_NETWORKS": "eip155:84532",
"VERIFY402_PAY_TO": "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb"
}
}
}
}
OpenCode V2 Configuration
In opencode.jsonc (or ~/.config/opencode/opencode.jsonc):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"verify402": {
"type": "local",
"command": ["npx", "-y", "verify402-mcp"],
"environment": {
"VERIFY402_URL": "https://verify402.onrender.com",
"EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}",
"VERIFY402_NETWORKS": "eip155:84532",
"MAX_PAYMENT_USD": "0.25",
"MAX_DAILY_USD": "1.00"
}
}
}
}
}
How AI Agents Use verify402 (Prompt Examples)
Once configured, your agent automatically sees the tools in its context. You can prompt it directly:
- Preflight Gate (Free):
"Before signing this transaction, call
preflight_gateon the payment request / calldata. If it returns BLOCK, abort and explain why." - Token Quote-Based Sellability Check ($0.10, not a code audit):
"Analyze token
0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cEusingcheck_token_safety. Can it be sold at a realistic size on the configured venues, what is the round-trip cost, and is the result TRUST / CAUTION / AVOID? Read notChecked for transfer restrictions." - Arbitrage Verification ($0.05):
"Use
verify_arbitrageto verify if there is an arbitrage opportunity between Uniswap V3 and Sushiswap for WETH/USDC on chain 1 at the current block." - Quote Fairness Audit ($0.05):
"I was offered 0.35 WETH for 1,000 USDC. Run
verify_quote_fairnessto see if this is fair or if I'm overpaying." - Market Depth & Capacity ($0.05):
"Check
get_trade_depthfor WETH on Uniswap V3 to see how much slippage and impact a $50,000 swap would suffer."
Safety
- The bridge signs x402 payments only. It never signs or broadcasts a trade.
- Each paid tool call mints one
crypto.randomUUID()idempotency key and sends it asx-idempotency-key. A timeout or lost response is retried with the same key, so the server replays the settled verdict (recovery.replayed: true) instead of charging twice. A 402 or 409 is never auto-retried; the error is surfaced to the MCP client. The key is a secret and is never logged or returned. - 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 whole 402 challenge is checked, not just the option the client picks:
every offered requirement must use an allowlisted network, the configured
payee, the canonical USDC contract and the canonical EIP-712 domain for
that network, an
extra.assetTransferMethodofeip3009, amaxTimeoutSecondsthat is a positive integer no greater than300, and an amount inside the cap. A challenge that also offers Base mainnet is refused as a whole rather than filtered down to the testnet option. The client also proves that the requirement it signs is the exact object the server sent. - The allowlist can be narrowed or pointed at another deployment with
VERIFY402_NETWORKS,VERIFY402_PAY_TO, andVERIFY402_RESOURCE_PREFIX. The bridge defaults are Base Sepolia testnet (eip155:84532) and the public verify402 payee.VERIFY402_NETWORKSis constrained to the supported map (eip155:84532,eip155:8453); an explicitly empty value fails closed instead of falling back to a default. MAX_PAYMENT_USDis enforced inside the x402 client, before a signature exists; removing it is a security regression. The caps limit what the bridge can authorize; they do not protect a compromised private key.- The bridge sends
X-Verify402-Client: verify402-mcp/<version>and the same version in its User-Agent. This is an anonymous label for/usage, not an account: it contains no wallet, key, or user id, and the server treats it as self-declared and spoofable. preflight_gateis a check, not a guarantee. ReadnotChecked: it does not screen recipient reputation or sanctions, audit contracts, simulate full balance deltas, audit the counterparty, independently prove payee ownership, persist an obligation ledger across processes, scan tool descriptions or responses for prompt injection, or protect against MEV. It catches the measurable signing mistakes, not every scam.- Use the reference executor when you want enforcement rather than advice.
Dependencies and npm audit
This package no longer depends on @x402/axios or @x402/evm. The x402 payer
(PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE, scheme exact,
EIP-3009 authorization) is implemented here on viem, and the runtime
dependency list is: the MCP SDK, axios, dotenv, viem, zod 4.
Why: @x402 2.28.0 depended on zod ^3.24.2, which resolves into
GHSA-mrhx-c7xc-m3w5
(memory-exhaustion DoS while validating oversized arrays; the advisory covers
all zod < 4.6.6, and no patched 3.x exists). npm ignores overrides declared
inside a dependency, so installs of 1.0.8 and earlier showed a "high severity"
audit banner. The upstream request is
x402-foundation/x402#3953.
The current package, installed from its tarball:
$ npm i verify402-mcp
added 123 packages
$ npm audit
found 0 vulnerabilities
The bridge pays the same wire protocol. The only behavior change is cosmetic:
npm ls @x402 shows nothing, and the install is 5 packages smaller. The
paid-call policy (network allowlist, configured payee, canonical USDC,
per-payment cap, tool-bound resource) is unchanged and still runs before any
signature exists, in payment-policy.mjs.
Explicit mainnet configuration (not the public demo)
Mainnet settlement is a separate deployment choice, not a bridge or demo default. Do not point this client at mainnet until the service-side mainnet readiness checks, facilitator, always-on host, and wallet funding have been verified independently.
# Only for a deliberate mainnet deployment, never against the public demo.
VERIFY402_NETWORKS=eip155:8453
VERIFY402_PAY_TO=<the payee named by the mainnet 402>
The public demo offers eip155:84532; a mainnet-only policy will refuse that
challenge instead of silently spending mainnet funds. The reverse is also
enforced: the demo policy refuses a mainnet-only challenge.
Development
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.