Concepts

Bloomfilter uses three key protocols. Understanding them will help you work with the API effectively.

x402 — HTTP payments

x402 is an open protocol that adds native payments to HTTP. When you request a paid endpoint without paying, the server responds with HTTP 402 Payment Required — the status code that HTTP reserved for payments since 1997.

How it works:

1. Client sends a request to a paid endpoint (e.g. POST /domains/register)
2. Server responds with 402 + a PAYMENT-REQUIRED header containing payment details (price, asset, network)
3. Client signs a USDC payment on Base L2
4. Client retries the request with a PAYMENT-SIGNATURE header
5. Server verifies and settles the payment on-chain, then processes the request

Two pricing models:

Model	Endpoints	Price
Dynamic	POST /domains/register, POST /domains/renew	Varies by TLD + years
Static	POST /dns/*, PUT /dns/*, DELETE /dns/*	$0.10 per operation

Tip

If you’re using the MCP server or @x402/axios, the payment flow is handled automatically. You don’t need to implement x402 manually.

For a detailed walkthrough, see the x402 Payment Flow guide.

SIWE — Wallet-based authentication

SIWE (Sign-In With Ethereum) replaces traditional username/password auth with wallet signatures.

How it works:

1. Client requests a nonce from GET /auth/nonce
2. Client constructs a standard EIP-4361 message with the nonce
3. Client signs the message with their wallet private key
4. Client sends message + signature to POST /auth/verify
5. Server returns a JWT access token (1 hour) + refresh token (30 days)

Which endpoints need auth?

Requires auth	Endpoints
No	Search, pricing, registration, renewal, domain info, health
Yes	DNS management, account info, session revocation

Note

Registration and renewal don’t require SIWE auth — they use x402 payment as implicit identity. The wallet that pays is the domain owner.

For step-by-step instructions, see the Authentication guide.

Async provisioning

Domain registration usually completes instantly, but some registrations take longer (registry delays, premium domains, etc.). Bloomfilter handles this with HTTP 202 + job polling.

How it works:

1. Client sends POST /domains/register with payment
2. If registration completes within the timeout: 201 Created with domain details
3. If it takes longer: 202 Accepted with a jobId and poll_url
4. Client polls GET /domains/status/{jobId} until status is completed or failed

// 202 response
{
  "status": "pending",
  "jobId": "01JMXYZ...",
  "message": "Registration is being processed asynchronously",
  "poll_url": "/domains/status/01JMXYZ...",
  "poll_interval_ms": 2000
}

Tip

The MCP server handles job polling automatically. If you’re using the raw API, poll at the interval specified in poll_interval_ms.

For implementation details, see the Async Provisioning guide.