Skip to main content
Glama
wallet-guard
by lucas-low

wallet-guard

A pre-signing guard for crypto wallets. When a web app asks a wallet to sign something, wallet-guard works out what the signature would do and returns allow, warn or block with a plain-language reason, before the user sees the prompt.

Most losses here come from signatures the user was talked into: an unlimited token allowance to a stranger, a permit signed off-chain, setApprovalForAll to a drainer, an EIP-7702 delegation to hostile code, a payment to an address that imitates one they use, a site that looks like the real one.

Status: a reference implementation, not a product. It is not wired into a real wallet and has no users. The known-protocol list is a small seed. Treat the numbers below as what they are, a test of this design on a hand-built case set.

Use it from an agent (MCP)

An MCP server exposes two read-only tools over stdio, so any MCP client can check a signing request or an address before acting.

Tool

What it does

review_signing_request

Transaction, EIP-712 typed data or EIP-7702 authorization in, allow, warn or block out, with reasons. Deterministic rules only, no model.

inspect_address

Contract or wallet, EIP-7702 delegation, proxy kind and admin, Sourcify verification, SELFDESTRUCT, OFAC sanctions. A failed lookup returns unavailable, never a clean result.

{ "mcpServers": { "wallet-guard": { "command": "bunx", "args": ["--package", "wallet-guard", "wallet-guard-mcp"] } } }

Requires Bun. Ethereum mainnet only: a request for another chainId is rejected. Environment: ETH_RPC_URL (a mainnet endpoint, default a public RPC). Dapp-supplied text is not accepted by the schema, so a malicious description cannot reach the output.

Related MCP server: Lucent

Wallet middleware

guardProvider wraps any EIP-1193 provider (a browser wallet, a WalletConnect session, a bot's signer) so every signing request passes the policy floor before it reaches the key.

import { guardProvider } from "wallet-guard";

const provider = guardProvider(wallet, { chain, history, known, origin: "https://app.uniswap.org" });
await provider.request({ method: "eth_sendTransaction", params: [tx] }); // throws GuardRejection (code 4001) if blocked

It reviews eth_sendTransaction, eth_signTransaction, wallet_sendCalls (every call in the batch) and eth_signTypedData_v3/v4. A block verdict is refused. A warn is refused unless the onWarn callback accepts it. eth_sign, legacy eth_signTypedData, contract creation and any chain other than mainnet are refused rather than passed through unreviewed. personal_sign and read-only methods pass through.

How it decides

request ──► decode ──► rules (deterministic floor) ──► agent (explains, can only tighten) ──► verdict
                           │                               ▲
                  address facts, sanctions,         dapp text is quarantined:
                  origin check, history             the agent sees one boolean, not the text
  1. Decode. Calldata and typed data become an effect: transfer, token approval (bounded or unlimited), approve-all, permit, account delegation. Anything it cannot decode is reported as undecodable and warned on.

  2. Floor. Deterministic rules decide the minimum verdict: unlimited allowance, approval to a plain wallet, approve-all to an unknown operator, EIP-7702 delegation to an unknown contract, OFAC-sanctioned counterparty, address poisoning, lookalike origin (typos, digit swaps, punycode, brand-plus-word), insecure origin, first-time recipient.

  3. Agent. A model reads the request and the findings through read-only tools and writes the explanation. It can raise the verdict, never lower it.

  4. Fail closed. If the model errors, times out or never answers, the result is the stricter of the floor and warn. It is never allow.

  5. Quarantine. The text a dapp writes about itself is attacker-controlled. A separate tool-less classifier turns it into one boolean, and only that boolean reaches the agent.

The agent has no tool that signs or sends anything.

Run it

bun install
bun test                 # unit tests
bun run eval             # offline gates with scripted mock models
bun run cli demo         # all example requests, mock model and mock chain
bun run cli inspect 0x…  # what the chain says about an address: contract, proxy and admin, source verification, sanctions
MODEL_PROVIDER=ollama MODEL=qwen2.5:32b bun run cli check request.json

Real chain data: CHAIN_PROVIDER=onchain ETH_RPC_URL=<any JSON-RPC> uses the OFAC list in data/ofac-eth.txt plus eth_getCode, nonce and balance.

Measured on real history

Replayed at the block before each transaction, origin rule off, 2026-11-16:

Set

Cases

Block

Warn

Allow

Approvals and permits to labelled scam addresses (162,774 found, 1,200 sampled)

1,200

96.7%

3.3%

0%

Approvals from recent normal traffic, labelled spenders excluded

600

17.8%

72.7%

9.5%

Read the second row with care. It has no ground truth: some of those blocks are unlabelled scams or wallet-address spenders, so 17.8% is an upper bound on false alarms, and the 72.7% warnings are mostly spenders outside the 19-entry known list. Scam labels come from public lists, so a scam nobody has labelled is not counted. About 3% of cases could not be looked up. Methods and scripts: replay/.

Evals

bun run eval runs 25 cases (6 benign, 14 malicious, rest warn-level) against seven agent behaviours: competent, lenient (always allow), gullible, forgetful, broken, silent and slow. The gates check that no malicious case reaches the user below its minimum verdict whatever the agent does, that failures fail closed, and that the nudge turn recovers a forgetful model. These use scripted models, so they test the harness, not a real model. Live results against local models are in docs/evals.md.

Limits

  • EVM only. No Solana, no Bitcoin.

  • The known-spender and known-domain lists are a seed. A real deployment needs a maintained registry.

  • Origin matching uses the last two labels of a host, which is wrong for suffixes like co.uk.

  • Transaction simulation (balance changes before and after) is not implemented. It is the obvious next layer.

  • Calldata decoding covers the common approval, transfer and permit shapes only.

MIT licensed.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      MCP server that enables AI signing agents to pre-flight transactions by checking ERC-7730 descriptor safety, explaining function semantics, and scanning contracts for danger primitives.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to screen blockchain addresses and evaluate payment counterparties before funds move, returning clear/caution/risky verdicts, risk scores, and clickable evidence across EVM chains, Tron, and Solana. It also supports anti-blind-signing checks, x402 payment-requirement verification, identity/control baselines, and signed evidence bundles, with free tools and optional paid compliance tools.
      15
      444 npm
      MIT