three.ws Vanity

@three-ws/vanity-mcp

Read the three.ws vanity-address grind-bounty market + rarity gallery from any AI agent.

A Model Context Protocol server that gives any AI assistant the read/discovery surface of the three.ws vanity-address grind-bounty market over stdio. Quote how hard a Solana vanity pattern is and what to escrow for it, appraise the rarity of any address, and browse the live bounty board, claimable queue, stats, leaderboard, config, and the proof-of-grind gallery.

The market is secret-blind: a requester escrows a USDC bounty for a pattern, a fleet of independent workers grinds it in parallel, and the first to submit a verified key matching the pattern is paid on-chain — yet the found secret is sealed to the requester, so the worker earns the bounty without ever seeing the wallet. Posting a bounty and claiming one are the x402-paid write paths on the HTTP API; this MCP exposes the read/discovery + rarity surface. No API key, no signer, no payment — every call hits the public /api/vanity endpoints.

Install

npm install @three-ws/vanity-mcp

Or run with npx (no install):

npx @three-ws/vanity-mcp

Quick start

Claude Code, one line:

claude mcp add vanity -- npx -y @three-ws/vanity-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{

"mcpServers": { "vanity": { "command": "npx", "args": ["-y", "@three-ws/vanity-mcp"] } } }

Inspect the surface with the MCP Inspector:

npx -y @modelcontextprotocol/inspector npx @three-ws/vanity-mcp

Tools

vanity_quote and vanity_appraise are pure functions of their input (same pattern/address → same result), so they're marked idempotent. The other six read the live market and gallery.

Input parameters

`vanity_quote` — prefix (optional Base58 prefix), suffix (optional Base58 suffix), ignoreCase (bool, default false). At least one of prefix/suffix is required.

`vanity_appraise` — address (required, Base58 32–44 chars), prefixLen (int, optional), suffixLen (int, optional).

`vanity_board` — status (open | all | settled, default open), sort (recency | reward | expiry, default recency), limit (1–100, default 24), offset (default 0).

`vanity_open` — limit (1–100, default 30).

`vanity_stats` — no params.

`vanity_leaderboard` — limit (1–100, default 10).

`vanity_config` — no params.

`vanity_gallery` — sort (score | recency, default score), tier (string), minLength (int), contains (string), limit (1–100, default 24), offset (default 0).

Example

// vanity_quote

{ "prefix": "THREE" }

{ "ok": true, "pattern": { "prefix": "THREE", "suffix": null, "ignoreCase": false }, "difficulty": { "expectedAttempts": 11308763834, "rarityBits": 39, "tier": "mythic", "tierLabel": "Mythic", "accent": "#ff5db1", "expectedGrindSeconds": 7539 }, "oracle": { "floorAtomics": 50000, "suggestedAtomics": 2094216, "generousAtomics": 5235540, "maxAtomics": 5000000000, "expectedAttempts": 11308763834, "expectedGrindSeconds": 7539, "model": "58^effectiveLength @ refRate" }, "band": { "floorAtomics": 50000, "maxAtomics": 5000000000, "decimals": 6, "asset": "USDC" } }

Examples

Runnable examples live in examples/:

node examples/list-tools.mjs           # every tool with its full input schema

node examples/quote-and-appraise.mjs # config + quote + appraise + stats, live

Both spawn this server over stdio and read the live market. Every tool here is read-only, so nothing can be posted, claimed, or paid. See examples/README.md for expected output.

Requirements

• Node.js >= 20.
• Network access to https://three.ws (or your own THREE_WS_BASE).

Environment variables

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0, see LICENSE

Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.

Website · Changelog · GitHub