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": "", "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 201 on success, or 202 with a job ID for async provisioning.

POST /domains/renew

Body: { "domain": "example.com", "years": 1 }

years defaults to 1 if omitted.

-> Same two-phase x402 flow as registration.

Domain Info (free, no auth)

GET /domains/:domain

-> Returns domain status, expiry, nameservers, lock/privacy state.

Note: Only works for domains registered through Bloomfilter.

Job Status (free, no auth)

GET /domains/status/:jobId

-> Poll for async registration status. Returns 200 (done), 202 (pending), or 500 (failed).

DNS Management (requires Bearer token)

Mutations cost $0.10 USDC each (x402). Listing is free.

IMPORTANT: Always add, update, or delete DNS records one at a time (sequentially, not in parallel). After registering a new domain, wait at least 30 seconds before adding DNS records — the DNS zone may not be ready immediately.

GET /dns/:domain

-> List all DNS records

POST /dns/:domain

Body: { "type": "A", "host": "@", "value": "1.2.3.4" }

Optional: "ttl" (300-86400, default 3600), "priority" (for MX/SRV)

Supported types: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA

PUT /dns/:domain/:recordId

Body: { "host": "@", "value": "5.6.7.8" }

At least one field required. Optional: host, value, ttl, priority.

DELETE /dns/:domain/:recordId

-> Deletes the record

Account (requires Bearer token, free)

GET /account

-> Account summary (wallet, domain count, total spent)

GET /account/domains?limit=50&offset=0

-> Paginated list of owned domains

GET /account/transactions?limit=50&offset=0

-> Paginated transaction history

Notes

• All paid requests require an x402-compatible HTTP client with USDC on Base (chain ID 8453)
• WHOIS privacy is enabled by default on all registrations
• Docs: https://docs.bloomfilter.xyz

External Endpoints

No data is sent anywhere else. All requests go to the Bloomfilter API only.

Security & Privacy

• Your EVM_PRIVATE_KEY never leaves your local machine — it is used locally to sign x402 payment authorizations and SIWE messages
• The API receives your wallet address (derived from the key) but never the private key itself
• WHOIS privacy is enabled by default on all registrations — your identity is never exposed in public WHOIS records
• All API communication is over HTTPS

Trust

This skill connects to api.bloomfilter.xyz to register ICANN domains and manage DNS records. Payments are made in USDC on Base via the x402 protocol. Your private key stays local. Install only if you trust Bloomfilter (https://bloomfilter.xyz) as a domain registration provider.