three.ws Vanity

io.github.nirholas/vanity-mcp

Documentation

@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

Tool	Type	What it does
`vanity_quote`	read-only	Price a pattern: expected attempts, rarity tier, and an honest suggested USDC bounty. Idempotent.
`vanity_appraise`	read-only	Appraise any Solana address's rarity (pattern, score, bits, tier, attempts). Idempotent.
`vanity_board`	read-only	Browse the grind-bounty board — filter by status, sort by recency/reward/expiry, paginate.
`vanity_open`	read-only	List the claimable open-bounty queue workers poll.
`vanity_stats`	read-only	Live market totals: open count, USDC escrowed, USDC paid out.
`vanity_leaderboard`	read-only	Top grinders ranked by total USDC earned.
`vanity_config`	read-only	Payout availability + asset/network metadata (settlement asset, decimals, networks, pricing band).
`vanity_gallery`	read-only	Browse the proof-of-grind rarity gallery — sort, filter by tier/length/substring, paginate.

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": 656356768, "tier": "epic", "tierLabel": "Epic" },
  "oracle": { "suggestedAtomics": "500000", "suggestedUsdc": "0.50" },
  "band": { "floorAtomics": 50000, "maxAtomics": 50000000, "decimals": 6, "asset": "USDC" }
}

Requirements

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

Environment variables

Variable	Required	Default
`THREE_WS_BASE`	no	`https://three.ws`
`THREE_WS_TIMEOUT_MS`	no	`20000`