verdix-mcp: check an address before your agent sends it money

An MCP server that lets your AI agent check an EVM address on Base before sending it funds or approving a contract. It calls Verdix, which answers safe, caution or danger with the reasons. It checks:

• OFAC sanctions
• scam, phishing and exploit lists
• address-poisoning lookalikes, built from a live watch of every token transfer on Base
• contract age, code and provenance
• burn addresses

Each check is paid per call in USDC on Base via x402, from your own wallet. There is no account, no API key and no subscription. Your key never leaves your machine, and a price cap is enforced before anything is signed.

"Send 50 USDC to 0x4c3f…9e21": the agent calls check_address_risk first, gets "verdict": "danger", "reasons": ["address_poisoning"], and stops to ask you.

check_address_risk takes a tier argument, but an agent framework whose x402 client always pays the first price it's offered will end up paying quick regardless of what tier it asked for. The three check_address_risk_<tier> tools avoid that: each calls Verdix's single-tier endpoint (/risk/address/<tier>), which offers exactly one price, so any x402 client pays the tier the tool name says. Use whichever is simpler for your client; both reach the same risk checks.

Lite ($0.01, never "safe")

check_address_risk_lite is the cheapest check, meant for a quick screen before sending USDC to an address you don't know. It calls /risk/address/lite, which checks OFAC sanctions, scam and phishing lists, address-poisoning lookalikes, burn addresses, phishing tokens and flagged contract deployers. It skips address age and the caution-only contract checks.

Its verdict is no_known_risk, caution or danger, never safe. no_known_risk only means the address is on none of those lists. It is not a safety verdict. If you need safe (say, before a large transfer), use check_address_risk_quick ($0.02). The answer also carries limited_checks: true, checks_performed, not_checked and full_check. get_pricing lists quick/standard/deep in tiers, as before, and lite's price in a separate lite field.

What you need

• Node.js 18 or newer (it runs through npx, so there's nothing to install).
• A Base wallet holding a little USDC. You don't need ETH for gas: x402 payments are signed by you and settled on-chain by the payment facilitator. Use a dedicated wallet with a small balance (a few dollars) for your agent, not your main wallet.

Safety

• Your key stays on your machine. It is read from this server's environment and used only to sign each payment locally. It is never sent to Verdix or anywhere else, and never logged.
• Price cap. VERDIX_MAX_PRICE_USD (default 0.10, enough for lite, quick and standard) is the most one call may cost. A call above it is refused before anything is signed. To allow the deep tier, set it to 0.50.
• Only USDC on Base mainnet. Any other asset or network is refused.
• You pay only for complete answers. If Verdix can't complete a check (a data source is down), it answers 503 and the payment is not settled.

Setup

Replace 0xYOUR_PRIVATE_KEY with the key of your dedicated Base wallet.

Claude Desktop: one-click extension

1. Download verdix-mcp-<version>.mcpb from the latest release.
2. In Claude Desktop, open Settings → Extensions and drag the file in.
3. Click Install, then enter your wallet key and price cap.

The key is stored in your OS keychain. Node.js doesn't need to be installed, because Claude Desktop runs the extension with its own Node.js.

Claude Desktop: config file

Open Settings → Developer → Edit Config, which opens claude_desktop_config.json:

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

Add:

{
  "mcpServers": {
    "verdix": {
      "command": "npx",
      "args": ["-y", "verdix-mcp"],
      "env": {
        "VERDIX_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "VERDIX_MAX_PRICE_USD": "0.10"
      }
    }
  }
}

Then restart Claude Desktop.

Cursor

Put the same block in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "verdix": {
      "command": "npx",
      "args": ["-y", "verdix-mcp"],
      "env": {
        "VERDIX_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "VERDIX_MAX_PRICE_USD": "0.10"
      }
    }
  }
}

Don't commit a project-level .cursor/mcp.json that contains your key.

Claude Code

claude mcp add verdix -e VERDIX_PRIVATE_KEY=0xYOUR_PRIVATE_KEY -e VERDIX_MAX_PRICE_USD=0.10 -- npx -y verdix-mcp

Agent frameworks

Any MCP client that can launch a stdio server works. The command is npx -y verdix-mcp, with the environment variables below. Python example with the official MCP SDK:

from mcp import StdioServerParameters

verdix = StdioServerParameters(
    command="npx",
    args=["-y", "verdix-mcp"],
    env={"VERDIX_PRIVATE_KEY": os.environ["AGENT_WALLET_KEY"], "VERDIX_MAX_PRICE_USD": "0.10"},
)

Environment variables

What an answer looks like

check_address_risk returns Verdix's JSON exactly as the API sent it:

{
  "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "chain": "base",
  "tier": "quick",
  "price_usd": 0.02,
  "risk_score": 5,
  "verdict": "safe",
  "reasons": [],
  "checked": ["ofac", "scam_lists", "poisoning_watch", "onchain_age", "contract_code", "burn_list", "provenance"],
  "as_of": "2026-09-26T13:15:10.524501+00:00"
}

• danger: sanctioned, a known scam, exploit or phishing address, an address-poisoning lookalike, a burn address and similar. Don't send funds.
• caution: not enough evidence to call it safe. For example, it's new, an unverified contract, or one of the data sources was unavailable. Ask the user before sending.
• safe: every check ran and found nothing.
• no_known_risk (lite only, instead of safe): none of lite's lists know the address. Not a safety verdict; use quick if you need one.

The payment receipt (payer, on-chain transaction) is in the tool result's _meta under com.verdixapi/payment.

Troubleshooting

• "No wallet configured": VERDIX_PRIVATE_KEY isn't set in this server's env block.
• "Refusing to pay: … above your cap": raise VERDIX_MAX_PRICE_USD, or use a cheaper tier (lite is $0.01).
• "Verdix did not accept the payment": the wallet probably has too little USDC on Base. Call get_pricing to see the wallet address to fund.
• Answer with HTTP 503: a data source was down. You weren't charged; retry later.

License

MIT