X402check README

x402check — pre-payment risk checks for x402 agents and wallets

LIVE: https://x402check.xyz · did:web:x402check.xyz · $0.001 per evaluation with prepaid credits, or per call via x402 ($0.0035 on Base; $0.005 with transaction simulation) · discovery · DID document · JWKS

x402check is an x402 risk-check provider (wire format of x402 PR #2422). You call it before an agent or a wallet pays or signs, and it checks the counterparty. It combines provider-verified evidence with a typed model:

• the OFAC SDN list, refreshed daily;
• curated phishing and drainer feeds;
• transaction simulation: where the assets actually go, and which approvals are granted;
• drainer-kit code fingerprints, which recognize redeployed drainer contracts before their address is listed;
• our own kit watch: every Ethereum and Base block is read as it is produced. It records look-alike wallets that delegate (EIP-7702) to an address-poisoning executor, wallets whose delegate forwards whatever they receive (sweepers), and new contracts running drainer-kit code;
• look-alike domain analysis;
• on-chain facts about the counterparty, such as whether an approval is being granted to a plain wallet;
• a typed model (TypeSafe Jev) that reads the content the agent acted on for injected instructions.

Every verdict is an ES256 attestation. It states which checks the provider actually ran and which fields the caller merely asserted.

Scope, stated plainly. x402check catches what the chain, the lists, its own kit watch, and the content in front of it reveal. It does not see laundering patterns or other transaction-graph behaviour. It cannot flag an unknown drainer address that is simply sent funds, unless the address is one of the look-alikes or compromised wallets the kit watch has seen. A clean verdict means "none of these checks fired", not "safe". Measured limits are in docs/EVIDENCE.md.

_{The demo video predates v0.2.0. Its evidence slide shows v5 corpus numbers that EVIDENCE.md supersedes, and it predates the v0.3 layers (simulation, code fingerprints) and pricing (every evaluation is paid; there is no free tier).}

What it checks

Caller-supplied screening and authorization fields are recorded as asserted in the attestation and can never lower the score. Prose claims such as "already screened" are unverified by construction.

Quickstart

Every evaluation is paid; there is no free tier. There are two ways to pay:

• Prepaid credits: one x402 payment buys a balance, and each check then costs $0.001 with no payment round trip. This is the cheapest and fastest option.
• Per call: an x402 client pays when it gets the 402 and retries.

1. See the price. An unpaid call returns 402 with the accepted mainnet options in the PAYMENT-REQUIRED header:

   TerminalCopy

   curl -si -X POST https://x402check.xyz/v1/risk-check -H "Content-Type: application/json" -d '{"wallet":"0x7a3e8f0c2b1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f","chain":"base"}' | head -1
   # HTTP/2 402
   

2. Pay and check. Use the TypeScript SDK with an x402-paying fetch (see Payments), the MCP server, or any x402 client:

   server.tsCopy

   const verdict = await x402check.check({
     wallet: "0x7a3e8f0c2b1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f",
     chain: "eip155:1",
     domain: "https://app.example-dapp.org",
     context: "Permit2 signature: unlimited USDC allowance to this spender",
     interaction: { type: "permit_signature", unlimited: true },
     payment: { network: "eip155:1", asset: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", pay_to: "0x7a3e8f0c2b1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f" },
   });
   

The same request as the raw body the client sends:

curl -X POST https://x402check.xyz/v1/risk-check \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <x402 payment payload>" \
  -d '{
    "wallet": "0x7a3e8f0c2b1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f",
    "chain": "eip155:1",
    "domain": "https://app.example-dapp.org",
    "context": "Permit2 signature: unlimited USDC allowance to this spender",
    "interaction": { "type": "permit_signature", "unlimited": true },
    "payment": { "network": "eip155:1", "asset": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "pay_to": "0x7a3e8f0c2b1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f" }
  }'

{
  "checked": true,
  "score": 40,
  "tier": "high",
  "categories": ["intent_risk", "behavioral", "approval_to_eoa", "new_address"],
  "provider": "did:web:x402check.xyz",
  "evidence": {
    "sanctions": { "list": "ofac-sdn", "as_of": "2026-09-29", "status": "not_listed" },
    "domain": { "host": "app.example-dapp.org", "registrable": "example-dapp.org", "official": false, "impersonation": "none", "signals": [] },
    "onchain": { "status": "ok", "network": "eip155:1", "is_contract": false, "activity": "none", "tx_count": 0 },
    "feeds": [{ "source": "metamask-phishing-detect", "kind": "domain", "as_of": "2026-09-29", "status": "clear" }, "…"],
    "model": "jev-wallet-risk/v6"
  },
  "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6InJpc2stY2hlY2srand0Ii…",
  "jwks_url": "https://x402check.xyz/.well-known/jwks.json",
  "checked_at": "…", "expires_at": "…"
}

To also check what a transaction will do, send it as transaction ($0.005 per simulated evaluation). The provider simulates it against the latest block and reports the net asset movements, the approvals granted, and any findings:

curl -X POST https://x402check.xyz/v1/risk-check -H "Content-Type: application/json" -d '{
  "wallet": "0x…called contract or decoded counterparty…", "chain": "eip155:1",
  "transaction": { "from": "0x…user…", "to": "0x…contract…", "value": "0x2386f26fc10000", "data": "0x…" }
}'
# evidence.simulation → { "status": "ok", "outflows": [{ "standard": "native", "amount": "10000000000000000",
#   "counterparty": "0x…", "counterparty_is_contract": false }], "inflows": [], "approvals": [],
#   "findings": ["outflow_to_undisclosed_eoa"] }   → score capped at 40

Request fields

A field not in this table is refused (422 naming it), never ignored, and a mixed-case EVM address must carry a valid EIP-55 checksum.

Batch: POST /v1/risk-check/batch with {"requests": [...]} (≤ 25). It is all-or-nothing: an invalid item returns 422 with its index.

Attestation

A compact JWS (alg: ES256, typ: risk-check+jwt, kid as published in the DID document, today jev-attest-v1), TTL 1 h. Claims:

Verify it by pinning the issuer, and bind it to the request it answers. Never trust a key URL carried by a response or an intermediary:

npx tsx scripts/verify-attest.ts <jws> --request '<the exact JSON body>' --max-age 300 [--aud <url>] [--pay-to <addr> --amount <atomic>]

The reference verifier is the SDK's verifyAttestation behind a CLI. It resolves the key from the issuer's did:web document and pins x402check's key by default. It checks alg, typ, iss, exp and iat, and with --request it recomputes request_hash, so a verdict issued for another wallet, payment or transaction is rejected (request_mismatch). --max-age refuses an older verdict (plus a 300 s clock-skew allowance). Without --request, a valid verdict for something else still verifies.

Wallet integration

Check the real counterparty. For approve, a Permit2 signature or a Seaport order, that is the spender, operator or recipient decoded from the calldata or typed data, not the token contract. Send the interaction type too, and the transaction when you want it simulated. The MetaMask Snap in snap/ is a complete reference decoder.

The wallet (or its backend) pays each check with x402, so payingFetch below is a fetch wrapped with an x402 client, as in Payments:

const res = await payingFetch("https://x402check.xyz/v1/risk-check", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    wallet: spenderOrRecipient,              // decoded counterparty
    chain: `eip155:${chainId}`,
    domain: location.origin,                 // the requesting site
    context: "Permit2: unlimited USDC allowance to spender 0x…",
    interaction: { type: "permit_signature", unlimited: true },
  }),
});
if (res.status !== 200) return showNotVerified(res.status);   // 402 = payment not settled: never an all-clear
const v = await res.json();
if (!v.checked) return showNotVerified();                     // fail-closed, never an all-clear
if (v.tier === "high" || v.tier === "critical") warnOrBlock(v);

Payments

Every evaluation is paid; there is no free tier.

Prepaid credits (recommended):

• POST /v1/credits {"amount_usd": 1} returns a 402 for $1.00 on any network. Pay it with any x402 client and the response carries a token (x402c_…, shown once) and its balance. Packs run from $0.10 to $100.
• Send Authorization: Bearer x402c_… with /v1/risk-check. Each check costs $0.001 ($0.005 when a transaction is simulated), debited atomically.
• Such a check has no 402 round trip and no on-chain settlement, so it is also several times faster.
• GET /v1/credits with the token returns the balance. POST /v1/credits with the token tops it up.
• To hold the token before you pay, generate it yourself and buy the pack as a top-up of it: x402c_ and 32 random bytes in base64url (node -e 'console.log("x402c_"+require("crypto").randomBytes(32).toString("base64url"))'), sent as Authorization: Bearer with the purchase. A token returned in the response is lost if the connection drops while the payment settles.
• If a verdict is not produced, the check is refunded, and a client that leaves before its check starts is not charged. Once the verdict is produced, the check is charged even if the client left.

Per call:

• Price by payment network (the 402 lists every network it offers): Base $0.0035, Solana $0.002, Sei $0.002, Avalanche $0.001, Monad $0.001, Polygon $0.007, Arbitrum $0.009.

• A request whose transaction is simulated costs $0.005, or the network's price if that is higher. The simulated price covers the simulation, the classification of every recipient and spender, and code fingerprints through delegations and proxies. It is charged only on chains where simulation runs.

• A batch is billed per item.

• Why the prices differ: every x402 payment is an on-chain settlement, and its cost is ours. PayAI settles EVM payments with EIP-3009, which any wallet can pay gaslessly, and bills us the network's gas + 30% per settlement (about $0.002 on Base on 2026-10-15). Dexter bills nothing, but on EVM networks it settles only through Permit2, which most payers' wallets cannot use without an on-chain approval. Coinbase CDP settles with EIP-3009 too, at $0.001 per settlement after 1,000 free a month, so it takes the EVM networks where it is cheapest.

• Routing: each network settles through a facilitator that does not cost more than the price; among those, one any payer can pay through, then the cheapest to us:

  • Coinbase CDP for Base, Polygon and Arbitrum ($0.001 per settlement after 1,000 free a month);
  • PayAI for Sei, and as the fallback for every EVM network;
  • Dexter for Solana and Monad (on Monad through Permit2, since CDP's fee there equals the price).

  A network whose every route would lose money is not offered until one clears its cost again: Avalanche since 2026-10-15, when PayAI's fee there rose to $0.0057 against a $0.001 price.

  /status shows each network's facilitator, transfer method, fee and margin live. It also lists each facilitator's health and published signers, so anyone can check on-chain who settled a payment.

• Settlement: USDC via x402 v2 (PAYMENT-SIGNATURE), mainnet only: Base, Polygon, Arbitrum, Avalanche, Monad, Sei and Solana. The x402 "exact" scheme is gasless for the payer, so USDC alone is enough.

• An unpaid request gets 402 with the accepted options in PAYMENT-REQUIRED, whatever its body. Any x402 client pays and retries.

• Invalid input is never charged: with a payment or a token it is rejected (/) before any payment work; unpaid, the says why in .

import { createClient } from "@x402check/client";
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const payer = new x402Client();
payer.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`)));
payer.setSpendControls({ maxAmountPerPayment: "$1" });

// Once: buy credits (one x402 payment). Store the token like a password.
const { token } = await createClient({ fetch: wrapFetchWithPayment(fetch, payer) }).buyCredits(1);

// Every check after that: $0.001 from the balance, no payment round trip.
const x402check = createClient({ creditToken: token });
const verdict = await x402check.check({ wallet: "0x…", chain: "base" });

// Or pay per call instead: createClient({ fetch: wrapFetchWithPayment(fetch, payer) }).

Architecture

request ─► validate (422 names the field) ─► credits debit, or x402 payment (per item) ─► Provider
                                                                         │
      deterministic, provider-side ──────────────────────────────────────┤
        OFAC SDN screen ── listed? ──► score 0 · critical (no model call)│
        domain analysis (PSL, homoglyph, typosquat, lure)                │
        threat feeds (MetaMask + OFAC refreshed daily, ScamSniffer KV)   │
        on-chain facts + code fingerprints (JSON-RPC)                    │
        transaction simulation (eth_simulateV1) + contract verification  │
      model ─ Jev typed questions over provider checks + context ────────┤
      code  ─ weights, deterministic caps, tiers (src/scoring.ts) ───────┤
                                                                         ▼
         settle payment (per call) ─► release ES256 attestation: checks · asserted · payment · jti

Source layout:

• src/: provider, validation, enrichment, simulation, code fingerprints, scoring and JWS.
• deploy/: the Cloudflare Worker: the x402 paywall and pricing, facilitator routing, feed refresh and /status. See deploy/README.md.
• packages/: the TypeScript SDK (client) and the MCP server (mcp).
• snap/: the MetaMask Snap.
• eval/: evaluation layers and production probes.
• scripts/: data refresh, the feeds publisher and the verifier.
• docs/: METHODOLOGY, EVIDENCE, STRATEGY.

Evidence (v0.4–v0.6)

Full methodology, confidence intervals and what each number does not show: docs/EVIDENCE.md. How each verdict is formed, with every cap: docs/METHODOLOGY.md. Earlier evidence documents are kept as historical records with correction notes.

Run locally

npm install
npm test                           # provider unit tests
npm run typecheck                  # root + deploy + scripts + snap
AI_GATEWAY_API_KEY=... npm start   # :8799 local dev server, no paywall (or TYPESAFE_API_KEY=...)
curl localhost:8799/.well-known/risk-check.json
npm run eval:suite -- --seed 200   # full evaluation (~$0.15 of model calls)

Worker: npm run dev:worker, or wrangler dev --local in deploy/. See deploy/README.md for secrets, feeds, deploy and rollback.

For agents: SDK and MCP server

• @x402check/client is a typed TypeScript client with zero runtime dependencies. It runs on Node ≥ 20, browsers, Cloudflare Workers, Deno and Bun.
  • verifyAttestation checks the signature against the issuer's did:web key and binds it to the request you made, including request_hash.
  • interpret applies the fail-closed policy. Its verdicts come from the signed claims only, never from the unsigned body.
  • guardAccount (@x402check/client/guard) makes the check enforced, not advisory. It wraps the account an agent signs with, and every transaction, permit, order, x402 payment or EIP-7702 delegation is signed only after a verified allow bound to that exact request. Otherwise it throws, and the key never signs. A transaction is signed only on its simulation (the verified attestation must say simulation.status: "ok"), so on a chain the provider does not simulate it is not signed. The exceptions are stated: an x402 payment of up to $0.25 to x402check's own pay_to (paying for a check) is not checked; a request with no counterparty and nothing to simulate (e.g. a zero-value deployment) is signed as inert; and a warn is signed when your onWarn approves it. See the signing guard.
• @x402check/mcp is an MCP server for any agent (Claude Code, Claude Desktop, other MCP clients), with the tools x402check_check, x402check_pay, x402check_verify_attestation and x402check_methodology.
  • Every verdict is verified before the agent sees an action.
  • x402check_pay fetches an x402 resource and pays only after x402check clears the exact payee, right before signing. A warn goes to the user in the client, never to the agent.
  • It pays each check from prepaid credits (X402CHECK_CREDIT_TOKEN) or itself via x402 (USDC on Base, gasless for the payer), with a per-payment cap and a total budget. Both secrets are redacted from every output.

# with prepaid credits ($0.001 a check, no payment round trip):
claude mcp add x402check -e X402CHECK_CREDIT_TOKEN=x402c_… -- npx -y @x402check/mcp
# or paying per call from a dedicated wallet with a small USDC balance on Base:
claude mcp add x402check -e X402CHECK_PAYER_KEY=0x… -e X402CHECK_BUDGET_USD=1 -- npx -y @x402check/mcp

Both packages are on npm:

• @x402check/client;
• @x402check/mcp.

The MCP server is also in the official MCP Registry as io.github.caiovicentino/x402check.

Discovery: agents and their developers can find x402check in three catalogs.

• The x402 Bazaar, which Coinbase CDP builds from the payments it settles. It lists /v1/risk-check and its batch endpoint, with the input schema, a callable example and the price on each network (GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources).
• x402scan, which reads /openapi.json. That document declares each paid operation's price range, schemas and agent guidance.
• The official MCP Registry, where the MCP server is listed as io.github.caiovicentino/x402check (npm @x402check/mcp).

Opening an endpoint in a browser returns an example request and the prices.

MetaMask Snap (preview)

snap/ has onTransaction / onSignature insights that decode the request locally and show the real counterparty, the amounts (including UNLIMITED approvals) and local danger findings.

Every check is paid, and this Snap version cannot pay yet. So 0.3.0 sends nothing to x402check.xyz and has no network permission. Every insight says "NOT verified by x402check" and never shows an all-clear.

The paid mode is complete and tested behind a single flag (src/config.ts), ready for when wallet-side payment exists. It checks the counterparty, simulates the transaction ("You send 1.5 ETH → 0x… (wallet)"), and renders the signed verdict with its evidence and warnings for hidden recipients and known drainer code.

Supported decoding:

• calldata: ERC-20 approve / transfer, Permit2, EIP-2612, setApprovalForAll, NFT transfers;
• typed data: v1, v3 and v4, including Permit2 and Seaport;
• personal_sign messages, decoded to text.

On install and on update it shows a disclosure that states exactly what happens. In this version nothing is sent. It stores only which disclosure you have seen.

cd snap && npm install && npm test          # builds, then 322 tests (285 run; paid-mode scenarios also run in Node) incl. the built bundle in SES
npx mm-snap serve                           # then wallet_requestSnaps "local:http://localhost:8062" in MetaMask Flask

The Snap is not yet published to npm nor allowlisted by MetaMask, so there is no one-click install in regular MetaMask yet.

Data handling

What a check sends where, so you can decide what to put in a request:

• The model vendor. TypeSafe's Jev model, reached through the Vercel AI Gateway, receives the request's fields (including context) and the provider's own findings. Before that, the server redacts private keys, seed phrases and x402check credit tokens from context. Nothing else is redacted. We have not yet confirmed the vendor's retention terms, so leave secrets and personal data out of context.
• Public RPC operators and Blockscout receive the addresses and, for a simulation, the transaction.
• Cloudflare runs the Worker. Workers Logs keep only the Worker's own log lines, which by design carry no request bodies or tokens; invocation logs are off (invocation_logs = false), so no request metadata or header is stored there. Cloudflare's zone analytics still count requests by path, status, user agent and country.
• x402check's KV keeps a record of each settlement (network, transaction, route) for 400 days, for reconciliation. Credit tokens are stored only as their SHA-256.
• Attestations carry what the verdict covers (sub, payment, interaction, aud) and hashes of the request (input_hash, request_hash), not the context itself.

Data sources and licenses

Code is MIT. Data sources:

• OFAC SDN (U.S. Treasury);
• MetaMask eth-phishing-detect (DBAD-1.2, embedded as a derived hash set, attributed);
• ScamSniffer scam-database (GPL-3.0, runtime only: never committed or bundled);
• Forta labelled datasets (MIT, derived code fingerprints);
• Blockscout and public JSON-RPC endpoints.

See THIRD_PARTY_NOTICES.md. OFAC and MetaMask are refreshed daily by .github/workflows/feeds.yml and swapped in at runtime after verification. /status shows the versions in use. Manual refresh: npm run ofac:update, npm run feeds:update.

Roadmap

The full roadmap is in docs/STRATEGY.md.

1. Shadow facilitator traffic continuously. The first week of PayAI-settled payments is replayed (v0.4), and a weekly report and an inline, log-only integration are offered to PayAI.
2. Measure the kit watch's lead time over the public lists as their listings arrive (they lag 7 days), and extend it to factory deployments (CREATE2 inside a contract) and to more chains.
3. Fresher address intelligence: funding-source analytics for plain transfers to wallets the watch has not seen.
4. Valuation-aware simulation rules (price data), closing the "return a dust asset" evasion.
5. Batch and upto payment schemes, to spread settlement gas when facilitators stop sponsoring it.
6. Wallet-side payment for the Snap, then publish it and request MetaMask allowlisting.
7. KMS/HSM custody for the attestation key. (Rotation with overlapping kids shipped in v0.6.0: a next key is published before it signs.)
8. Kora decision_provider integration (issue #682); AP2 RiskPayload once upstream stabilizes.