Bluepages
800K+ verified Ethereum address <> Twitter/X mappings, plus Farcaster.
Setup
Requires the Bluepages MCP server: npx -y github:bluepagesdoteth/bluepages-mcp
or direct API calls (see below). The MCP server is the recommended way to use Bluepages.
Authentication
Requires one of these env vars:
-
BLUEPAGES_API_KEY (recommended) — 20% cheaper, 2x rate limits.
-
PRIVATE_KEY — Ethereum private key for x402 pay-per-request (USDC on Base).
Security note: Never use a main wallet key. Use a dedicated, funded-only-as-needed agent wallet if providing PRIVATE_KEY .
With a private key, you can either pay per request via x402 or purchase a BLUEPAGES_API_KEY using the get_api_key and purchase_credits MCP tools.
Without a private key, the user must get an API key at bluepages.fyi/api-keys and set BLUEPAGES_API_KEY .
Tools (quick reference)
Tool Cost Description
check_address
1 credit ($0.001) Check if address has data
check_twitter
1 credit ($0.001) Check if Twitter handle has data
get_data_for_address
50 credits ($0.05) Full identity data for address (free if not found)
get_data_for_twitter
50 credits ($0.05) Full identity data for handle (free if not found)
batch_check
40 credits ($0.04) Check up to 50 items at once
batch_get_data
40 credits/found item Data for up to 50 items (x402: $2.00 flat/batch)
batch_check_streaming
same as batch_check For large lists (100+), shows progress
batch_get_data_streaming
same as batch_get_data For large lists (100+), shows progress
check_credits
free Check remaining credits (API key only)
set_credit_alert
free Set low-credit warning threshold (API key only)
get_api_key
free Get/create API key via wallet signature
purchase_credits
$5–$600 USDC Buy credits via x402 (PRIVATE_KEY only)
Input format
-
Addresses: 0x-prefixed, 42-char hex. Case-insensitive.
-
Twitter handles: With or without @ .
Cost-saving workflow
-
Single lookups: check_address /check_twitter first (1 credit), then get_data_* only if found (50 credits). Skipping the check wastes credits on misses.
-
Batch lookups: Always two-phase — batch_check then batch_get_data on found items only. This saves ~90% vs fetching everything blind.
-
Large lists (100+): Use _streaming variants for progress updates.
Rate limits
-
API Key: 60 req/min
-
x402: 30 req/min
-
Batch: max 50 items per request
Alternative: Direct HTTP API
If MCP is unavailable, call the API directly. Auth depends on your setup:
-
API key: pass X-API-KEY header
-
Private key (x402): endpoints return a 402 with payment details; sign and resend with X-PAYMENT header
With API key
curl "https://bluepages.fyi/check?address=0x..." -H "X-API-KEY: your-key" curl "https://bluepages.fyi/data?address=0x..." -H "X-API-KEY: your-key"
Batch check
curl -X POST "https://bluepages.fyi/batch/check"
-H "X-API-KEY: your-key" -H "Content-Type: application/json"
-d '{"addresses": ["0x...", "0x..."]}'
Full API docs: bluepages.fyi/docs