evm-vanity

Grind an EVM address that starts or ends with characters you choose, in your
browser, across every core, with an honest account of what it costs.

Try it without installing anything: npx wrangler deploy --temporary puts this
whole thing (site, API and discovery documents) on a Cloudflare Workers URL in
about thirty seconds and needs no account, no token and no configuration. That
preview is disposable and gets a fresh subdomain every time; npx wrangler deploy
with a Workers-scoped token puts it somewhere permanent.

A complete vanity wallet stack for Ethereum, Base, Arbitrum, Robinhood Chain and
every other EVM network: the browser grinder, the site, an HTTP API, a CLI, an
MCP server for AI assistants, EIP-712 provenance attestations a contract can
verify, and a delegation protocol that lets somebody else do the work without
ever being able to compute your key.

npx evm-vanity grind --prefix beef --keystore wallet.json

Why another vanity generator

1. Entropy, which is the only thing that has ever mattered here

In 2022 the most popular EVM vanity generator seeded its search from a 32-bit
value. Every key it had ever produced became searchable and tens of millions of
dollars were drained. This grinder draws a full 256-bit base scalar from the
platform CSPRNG, re-seeds every million candidates so no run extends one
arithmetic progression indefinitely, and re-derives every match through a
separate code path before emitting it. A key that does not control the address
it matched is never returned; there is a test for that.

2. Numbers that are not folklore

Every nibble of an EVM address is uniform, so 0x0000… is exactly as hard as
0xdead… and a suffix costs the same as a prefix. The number tools do get wrong
is casing: EIP-55 re-cases hex letters with keccak bits, so asking for a
specific spelling costs 2x per letter. dEaD is sixteen times harder than
any-case dead, and this project says so in every quote.

Grinding is geometric, so the mean is not a deadline. Quotes report p50, p90 and
p99 next to the expected value, because the tail is what a decision to start
actually depends on.

3. Delegation with no downside at all

Hard patterns need more compute than a browser tab has, and handing the job to
someone else normally means handing over the key. Split-key grinding removes
that trade with group arithmetic on secp256k1:

1. you pick a secret scalar k1 locally and publish only P1 = k1·G;
2. the grinder searches offsets k2 where the address of P1 + k2·G matches;
3. it returns k2, which is useless without k1;
4. you combine k = (k1 + k2) mod n on your own machine.

npx evm-vanity delegate --prefix beef

Private keys on secp256k1 are scalars, so the combined result is an ordinary
32-byte key that imports into MetaMask, ethers, viem, Rabby or a keystore file
like any other. (The Ed25519 version of this trick, on Solana, yields an expanded
key that seed-only wallets reject. Not here.) The attestation publishes k2·G,
so anyone can check address(P1 + k2·G) == address and confirm non-custody from
public values alone.

4. Provenance a contract can check

Attestations are EIP-712 typed data, not opaque blobs, so a marketplace, a
registry or an escrow recovers the signer with ecrecover in three lines of
Solidity and can refuse to list an address that is not provably ground and never
custodied. The same document verifies off chain, in the browser, with no RPC.

npx evm-vanity verify attestation.json

The exact type hash and domain separator are served at
/.well-known/evm-vanity.json so a deployed verifier and this library cannot
drift apart. The domain carries no chainId on purpose: an attestation is a
statement about an address, and an address is the same on every EVM chain.

Install and run

git clone https://github.com/nirholas/evm-vanity
cd evm-vanity
npm install
npm run dev            # site on http://localhost:5181, API on http://localhost:8788
npm test               # 52 tests

Production:

npm run build
ATTESTATION_KEY=<32-byte hex> npm start      # one process serves site + API

Cloudflare Workers, Docker, Cloud Run: see docs/deploy.md.

Install the CLI and library from npm:

npm install evm-vanity

import { addressFromPrivateKey, inspectAddress, splitKey } from 'evm-vanity';

const address = addressFromPrivateKey(privateKey);
const details = inspectAddress(address);
const requester = splitKey.generateRequesterShare();

The package root exports address helpers directly. Split-key, attestation,
chain, difficulty and validation helpers are available as namespaces; the
existing documented subpath imports remain supported.

One key, every chain

An EVM address is keccak256(pubkey)[12:]. It does not depend on a network, so
a single grind gives you the same address on Ethereum, Base, Arbitrum,
Robinhood Chain, OP, Polygon, BNB and Avalanche at once, and on chains that do
not exist yet.

The registry in src/chains.js exists for explorer links and
for the deterministic CREATE2 deployers, which matter only if you later want a
contract at a vanity address. Every row was verified with eth_getCode
against the listed public RPC, and both the chains page and
evm-vanity chains --verify re-run that check, so the table can be re-verified
rather than trusted.

The pieces

CLI

evm-vanity grind --prefix beef --suffix dead --keystore wallet.json
evm-vanity grind --prefix BeeF                 # EIP-55 spelling, 16x harder
evm-vanity delegate --prefix beef              # split-key, nothing leaks
evm-vanity quote --prefix dEaD --rate 17000
evm-vanity inspect 0xdEaD…
evm-vanity verify attestation.json
evm-vanity chains --verify
evm-vanity serve --port 8788
evm-vanity mcp

Add --json to anything for machine-readable output.

MCP

{
  "mcpServers": {
    "evm-vanity": { "command": "npx", "args": ["-y", "evm-vanity", "mcp"] }
  }
}

HTTP API

Full schema at /openapi.json; agent card at /.well-known/agents.json.

curl -s http://localhost:8788/api/quote \
  -H 'content-type: application/json' \
  -d '{"prefix":"dEaD","attemptsPerSecond":17000}'

Documentation

The site also ships its own documentation page at /docs.html.

Security model

Report vulnerabilities through GitHub security advisories. See SECURITY.md.

Environment

Provenance

The browser grinder, its worker, the pattern validation and the hex wordlist
were first built inside three.ws and are
re-licensed here under Apache-2.0. The secp256k1 split-key protocol, the EIP-712
attestation format, the chain registry, the API, the CLI and the MCP server are
new in this repository.

Licence

Apache-2.0. See NOTICE for attribution.

Star History

Support the project

If evm-vanity saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/evm-vanity and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors