bloomfilter

# Bloomfilter - Domain Registration API

Base URL: `https://api.bloomfilter.xyz`

Paid endpoints use the x402 payment protocol. The API returns HTTP 402 with payment details - your x402-compatible HTTP client handles payment automatically.

EVM_PRIVATE_KEY is used locally by the agent's x402 HTTP client (@x402/axios or @x402/fetch) to sign EIP-3009 TransferWithAuthorization messages for USDC payments and to sign EIP-4361 SIWE messages for authentication. The private key never leaves the local machine and is never sent to any server. All cryptographic signing happens client-side in the agent runtime.

DNS and account endpoints require authentication via SIWE (Sign-In With Ethereum). Authenticate once, then pass the JWT as a Bearer token.

## Authentication (SIWE)

GET /auth/nonce
-> Returns { nonce, domain, uri, chainId, version, expiresIn }

POST /auth/verify
Body: { "message": "<EIP-4361 SIWE message>", "signature": "0x..." }
-> Returns { accessToken, refreshToken, walletAddress }

POST /auth/refresh
Body: { "refreshToken": "..." }
-> Returns new { accessToken, refreshToken }

POST /auth/revoke (requires Bearer token)
-> Revokes all sessions for the authenticated wallet

## Domain Search & Pricing (free, no auth)

GET /domains/search?query=example&tlds=com,io,xyz
-> Returns availability and pricing for each TLD. The tlds parameter is optional.

GET /domains/pricing
-> Returns pricing for all supported TLDs

GET /domains/pricing/:tld
-> Returns pricing for a single TLD (e.g., /domains/pricing/com)

## Domain Registration (x402 - dynamic pricing)

POST /domains/register
Body: { "domain": "example.com", "years": 1 }
years defaults to 1 if omitted.
Optional: "dns_records": [{ "type": "A", "host": "@", "value": "1.2.3.4" }]
Supported dns_records types: A, AAAA, CNAME, MX, TXT, SRV, CAA
Each record also accepts optional "ttl" (300-86400, default 3600) and "priority" (for MX/SRV)
-> First call returns 402 with exact price. Retry with x402 payment to complete.
-> Returns 2...