# Bloomfilter API — AI Agent Reference

> Domain registration API for AI agents. Pay with USDC on Base L2 via x402 protocol.

Base URL: https://api.bloomfilter.xyz
Auth: SIWE (Sign-In With Ethereum) — JWT Bearer tokens
Payments: x402 protocol — USDC on Base (eip155:8453)
OpenAPI spec: https://docs.bloomfilter.xyz/openapi.json
Docs: https://docs.bloomfilter.xyz

## Endpoints

### Public (no auth, no payment)

GET /health — Service health check (DB, Redis, registrar status)
GET /.well-known/agent-card.json — ERC-8004 agent discovery card
GET /domains/search?query={q}&tlds={tlds} — Search domain availability (60/min)
GET /domains/pricing — All TLD pricing (registration, renewal, transfer in USD)
GET /domains/pricing/{tld} — Single TLD pricing
GET /domains/{domain} — Domain info (status, expiry, nameservers)
GET /domains/status/{jobId} — Poll async job status (200=done, 202=pending)

### Payment required (x402, no auth needed)

POST /domains/register — Register domain. Body: {domain, years?, dns_records?}. Price varies by TLD. 402→pay→201/202. (10/day)
POST /domains/renew — Renew domain. Body: {domain, years?}. Price varies by TLD. 402→pay→200. (10/day)

### Auth required (SIWE JWT)

GET /auth/nonce — Get SIWE nonce (30/min)
POST /auth/verify — Verify SIWE signature. Body: {message, signature}. Returns JWT tokens. (30/min)
POST /auth/refresh — Refresh JWT. Body: {refreshToken}. (30/min)
POST /auth/revoke — Revoke all sessions. (30/min)

### Auth + payment (SIWE JWT + x402 $0.10)

POST /dns/{domain} — Add DNS record. Body: {type, host, value, ttl?, priority?}. $0.10. (100/hr)
PUT /dns/{domain}/{recordId} — Update DNS record. Body: {host?, value?, ttl?, priority?}. $0.10. (100/hr)
DELETE /dns/{domain}/{recordId} — Delete DNS record. $0.10. (100/hr)

### Auth required (SIWE JWT, free)

GET /dns/{domain} — List DNS records. (100/hr)
GET /account — Account summary (wallet, spend, domains count)
GET /account/domains?limit=50&offset=0 — List owned domains
GET /account/transactions?limit=50&offset=0 — List transactions

## Common flows

### Register a domain
1. GET /domains/search?query=acme&tlds=com,io → find available domains
2. POST /domains/register {domain: "acme.io", years: 1} → 402 → pay USDC → 201 Created

### Add DNS record
1. GET /auth/nonce → get SIWE nonce
2. POST /auth/verify {message, signature} → get JWT
3. POST /dns/acme.io {type: "A", host: "@", value: "1.2.3.4"} → 402 → pay $0.10 → 201

### Renew a domain
1. POST /domains/renew {domain: "acme.io", years: 1} → 402 → pay USDC → 200

## DNS record types
A, AAAA, CNAME, MX (requires priority), TXT, NS, SRV, CAA

## Error format
{"error": string, "message": string, "code": "ERROR_CODE"}

## Error codes
VALIDATION_ERROR (400), TLD_NOT_SUPPORTED (400), DOMAIN_TOO_EXPENSIVE (400), AUTH_REQUIRED (401), TOKEN_EXPIRED (401), TOKEN_INVALID (401), PAYMENT_REQUIRED (402), PAYMENT_INVALID (402), PAYMENT_INSUFFICIENT (402), OWNERSHIP_DENIED (403), NOT_FOUND (404), DOMAIN_UNAVAILABLE (409), RATE_LIMITED (429), REGISTRATION_FAILED (500), DNS_ERROR (500), SERVICE_UNAVAILABLE (503)

## MCP server
npm: @bloomfilter/mcp-server
Config: {"command":"npx","args":["-y","@bloomfilter/mcp-server"],"env":{"BLOOMFILTER_PRIVATE_KEY":"0x...","BLOOMFILTER_NETWORK":"eip155:8453"}}

## Skill
ClawHub: clawhub install bloomfilter
SKILL.md: https://bloomfilter.xyz/SKILL.md