x402check

@x402check/mcp

An MCP server that lets any AI agent check a counterparty before money moves, with x402check, and pay for x402 resources only after the payee is cleared. It is a stdio server built on the official @modelcontextprotocol/sdk.

Each check screens the counterparty against the OFAC SDN list, phishing and drainer feeds, look-alike domains and on-chain facts. It can also simulate the transaction (API v0.3), and a typed model reads the content the agent acted on. The server verifies every verdict's ES256 attestation against did:web:x402check.xyz before the agent sees an action.

Every check is paid. There is no free tier, and the agent never handles money. The server pays one of two ways:

• From prepaid credits (`X402CHECK_CREDIT_TOKEN`): $0.001 a check, or $0.005 when a transaction is simulated, with no payment round trip. Buy a token with POST https://x402check.xyz/v1/credits or the SDK's buyCredits.
• Per call via x402 (`X402CHECK_PAYER_KEY`): from a wallet you configure, at the payment network's price ($0.0035 on Base), with a per-payment cap and a total budget.

Install

Claude Code

# prepaid credits: $0.001 a check, no payment round trip

claude mcp add x402check -e X402CHECK_CREDIT_TOKEN=x402c_YOUR_TOKEN -- npx -y @x402check/mcp

or per call via x402, from a dedicated wallet

claude mcp add x402check \ -e X402CHECK_PAYER_KEY=0xYOUR_DEDICATED_WALLET_KEY \ -e X402CHECK_BUDGET_USD=1.00 \ -e X402CHECK_MAX_PAYMENT_USD=0.05 \ -- npx -y @x402check/mcp

both: checks from credits, and x402check_pay pays cleared resources from the wallet

claude mcp add x402check \ -e X402CHECK_CREDIT_TOKEN=x402c_YOUR_TOKEN \ -e X402CHECK_PAYER_KEY=0xYOUR_DEDICATED_WALLET_KEY \ -- npx -y @x402check/mcp

Without X402CHECK_CREDIT_TOKEN or X402CHECK_PAYER_KEY, the server still starts. Every check then returns not_verified, with instructions to configure one of them. x402check_pay needs X402CHECK_PAYER_KEY: credits pay for checks, never for resources.

Claude Desktop

Add the server to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{

"mcpServers": { "x402check": { "command": "npx", "args": ["-y", "@x402check/mcp"], "env": { "X402CHECK_PAYER_KEY": "0xYOUR_DEDICATED_WALLET_KEY", "X402CHECK_BUDGET_USD": "1.00", "X402CHECK_MAX_PAYMENT_USD": "0.05" } } } }

Any other MCP client

Run npx -y @x402check/mcp, or x402check-mcp after npm install -g @x402check/mcp, as a stdio server. The server needs Node.js 22 or later, on its latest security release (22.23.4, 24.22.1 or 26.12.1 or later as of 2026-10-21): it holds a payer key and talks to servers it does not know.

From a local checkout

# from the repository root; the server depends on the client via file:../client, so build the client first

npm --prefix packages/client ci && npm --prefix packages/client run build npm --prefix packages/mcp ci && npm --prefix packages/mcp run build node packages/mcp/dist/index.js --help

Then register the built entry point with an absolute path. Quote it if it contains spaces.

claude mcp add x402check -e X402CHECK_PAYER_KEY=0xYOUR_DEDICATED_WALLET_KEY -- node "/absolute/path/to/repo/packages/mcp/dist/index.js"

{

"mcpServers": { "x402check": { "command": "node", "args": ["/absolute/path/to/repo/packages/mcp/dist/index.js"], "env": { "X402CHECK_PAYER_KEY": "0xYOUR_DEDICATED_WALLET_KEY" } } } }

Configuration

| X402CHECK_CREDIT_TOKEN | none | A prepaid credit token (x402c_…, from POST /v1/credits). • Each check is debited from its balance: $0.001, or $0.005 when a transaction is simulated. There is no payment round trip. • For checks, it takes precedence over X402CHECK_PAYER_KEY. • What this process spends from it is capped by X402CHECK_BUDGET_USD (below); the balance is a second cap. • An empty balance returns not_verified, with the top-up to do. | | X402CHECK_PAYER_KEY | none | EVM private key (0x + 64 hex) of the wallet that pays, in USDC via x402, on Base when offered: • the x402 resources x402check_pay clears; • the checks themselves, when there is no credit token. See the security note below. | | X402CHECK_MAX_PAYMENT_USD | 0.05 | The most a single payment may cost, a check or a resource. A higher price is refused before anything is checked or signed. | | X402CHECK_BUDGET_USD | 1.00 | The spend cap of this server process, applied twice, separately: • the payer: checks paid per call and x402check_pay payments together. Every signed payment that was sent counts, settled or not; • prepaid credits: what checks spend from X402CHECK_CREDIT_TOKEN, tallied from the API's X-Credits-Charged header. A check with no answer stays counted, since it may have been charged; an HTTP error is not charged, so it is not counted. Once a budget cannot cover the next check or payment, it is refused without calling the API, and the result says which budget ran out (budget_exhausted). A restart resets both. | | X402CHECK_BASE_URL | https://x402check.xyz | API origin, for example a staging or local provider. x402check_pay pays x402check's own pay_to without a check only on this origin. | | X402CHECK_ISSUER | did:web:x402check.xyz | The attestation issuer this server trusts. It is the trust anchor, so it is operator configuration only and never a tool argument. | | X402CHECK_PINNED_KEYS | x402check's own keys | Comma-separated RFC 7638 SHA-256 thumbprints (base64url) of the attestation keys accepted, in every verification: x402check_check, x402check_pay and x402check_verify_attestation. A key outside the list fails with key_not_pinned, even when the issuer's DID document serves it. • For did:web:x402check.xyz, the default is @x402check/client's X402CHECK_KEY_THUMBPRINTS, the same pins as the signing guard. • Another issuer is pinned only when its keys are listed here (the startup line on stderr says so). • Pinning cannot be switched off from the environment, and an unusable list fails at startup. | | X402CHECK_TIMEOUT_MS | 30000 | Per API call (a paid call is two round trips plus settlement), and per request to an x402 resource: until its headers arrive, and for a 402 until its body is read. |

Security: the payer key is a hot key

• Use a dedicated wallet that holds only a small USDC balance on Base, for example a few dollars. Never use a wallet that holds anything else. The server signs payments to x402check without asking anyone: for its own checks, and for resources on x402check's own site (X402CHECK_BASE_URL). Payments to any other payee, including a site that names x402check's pay_to, are signed only after x402check allows them (or the user approves a warning).
• A check is paid only to x402check, and never more than a check costs (at most $0.01, above every published price). A 402 from the API origin that names another payee, or asks for more, is not paid (untrusted_check_payee, over_check_price): a hijacked API domain cannot collect from the payer.
• The payer needs no ETH. The x402 "exact" scheme is gasless for the payer: it signs a USDC transfer authorization (EIP-3009), and the facilitator settles it.
• Spending is bounded. X402CHECK_MAX_PAYMENT_USD caps each payment (x402 spend controls). X402CHECK_BUDGET_USD caps the total for the process: the payer's, and separately what checks spend from prepaid credits.
• A signed authorization is short-lived. It is valid for at most 15 minutes (the 402's maxTimeoutSeconds, capped at 900), so a payee that holds one back can settle it only within that window.
• The key is never logged or echoed. It lives only inside the signer, and every tool output is scrubbed of it. At startup, stderr shows the payer's public address and limits, never the key.
• The credit token is a bearer secret, like an API key. Anyone who holds it can spend its balance. It is never logged or echoed, and every tool output is scrubbed of it. Keep the balance small and top it up as needed.
• Solana payment is not built in, to keep the dependency surface of a key-holding process small. @x402check/client accepts any x402-paying fetch, including a Solana one. The runtime dependencies are the MCP SDK, the x402 and viem packages, zod, and undici (Node.js's own HTTP client, which pins resource connections to checked addresses).

How an agent should use it

The server's instructions and the tool description tell the agent the following:

• Call x402check_check before it sends funds, signs a token approval, permit or order, or pays an x402 invoice.
• Check the real counterparty: the recipient, spender, operator or pay_to, not the token contract.
• Pass the chain, the site, and the content it acted on (context), verbatim.
• Pass transaction (EVM from, to, value, data) to have the transaction simulated.
• Then follow the action:

The tool does not accept caller assertions (screening, authorization), because claims such as "already screened" are not evidence.

What the agent reads

x402check: BLOCK. Do not proceed.

Checked 0x7a3e8f0c2b1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f on base for permit_signature (unlimited) from https://app-uniswap.org Why:

• Drainer pattern: assets leave the sender, nothing comes back, and a plain wallet (EOA) the sender did not name ends up with them: erc20 0x8335…2913 250000000 → 0x9999…9999 (EOA)
• Drainer pattern: an approval or permit grants a plain wallet (EOA) control over the user's assets: permit2 0x8335…2913 UNLIMITED to 0x7a3e…6e7f (EOA)
• Unlimited allowance: permit2 0x8335…2913 UNLIMITED to 0x7a3e…6e7f (EOA)
• Risk tier critical, score 10/100 (higher is safer)

Evidence: OFAC SDN not listed (list as of 2026-09-23) · on-chain: plain wallet (EOA), no history on eip155:8453 · domain app-uniswap.org: imperso