# wallettriage-mcp

<!-- mcp-name: io.github.wallettriage/wallettriage-mcp -->

MCP server for [WalletTriage](https://wallettriage.com) — real-time exploit-exposure
check for EVM wallets, built for AI agents. Each query is **paid via x402**
(USDC on Base) signed locally by a session key: no signup, no API key, no prompts.
Stateless — nothing about you or your queries is persisted.

## Tools

- **`check_address_risk`** (paid) — real-time risk for an EVM address: dangerous
  ERC20 approvals cross-referenced with a live threat feed of contracts under
  attack. Returns `risk_score` (0–100), `risk_level` and actionable `findings`.
- **`get_pricing`** (free) — service status and current price per query.

## Setup (Claude Desktop, Claude Code, Cursor)

Requires Node 20+. Add to your MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "wallettriage": {
      "command": "npx",
      "args": ["-y", "wallettriage-mcp"],
      "env": {
        "GATEWAY_URL": "https://api.wallettriage.com",
        "EVM_PRIVATE_KEY": "0xREPLACE_WITH_SESSION_WALLET_PRIVATE_KEY",
        "MAX_PAYMENT_ATOMIC": "100000"
      }
    }
  }
}
```

Fund the session wallet with a few USDC on Base. **Use a dedicated, low-balance
wallet — never your main key.** It only signs gasless EIP-3009 USDC payments;
WalletTriage never holds or moves funds.

`EVM_PRIVATE_KEY` is the wallet's **private key** (0x + 64 hex), not its address.
No ETH needed — payments are gasless (EIP-3009). Test connectivity first with the
free `get_pricing` tool before funding.

Then ask your agent: *"Check the risk of 0xd8dA… before I interact with it."*

## Troubleshooting

- **`unable to verify the first certificate`** (common on Windows / corporate
  networks): your antivirus or proxy intercepts TLS and Node doesn't use the
  system certificate store by default. Add `"NODE_OPTIONS": "--use-system-ca"`
  to the `env` block. Never disable TLS verification — payments travel in
  headers and must not be tamperable.
- **`EVM_PRIVATE_KEY is malformed`**: the value must be `0x` + 64 hex characters
  (the private key of the session wallet). Check for placeholder text, missing
  `0x` or stray whitespace.
- **`Gateway unreachable`**: `GATEWAY_URL` defaults to
  `https://api.wallettriage.com`. If you overrode it (e.g. to a local gateway),
  make sure that host is reachable and running.

## Environment variables

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `EVM_PRIVATE_KEY` | yes | — | Session key that signs x402 payments (USDC on Base) |
| `GATEWAY_URL` | no | `https://api.wallettriage.com` | WalletTriage API base URL. Defaults to production; set `http://localhost:4021` for local dev (https enforced for non-local hosts) |
| `MAX_PAYMENT_ATOMIC` | no | `100000` (US$0.10) | Refuses any 402 requirement above this cap (atomic USDC units, 6 decimals) |
| `DEFAULT_SCAN_CHAIN` | no | `eth` | Default chain: eth, base, polygon, arbitrum, optimism, bsc |

## Local development

```bash
npm install
cp .env.example .env   # set EVM_PRIVATE_KEY
npm start              # runs src/server.ts via tsx (stdio)
```

Point at a local gateway with `GATEWAY_URL=http://localhost:4021`, or test with
the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector npx tsx src/server.ts
```

`npm run build` emits `dist/server.js` (the published `bin`).