Skip to content
Bloomfilter Bloomfilter

Register a domain

POST
/domains/register

Registers a new domain name. This endpoint uses x402 dynamic pricing — the first request returns a 402 with payment details, and the client must retry with a valid x402 payment header. Rate limited: 10 requests per day per IP.

Request Body required

Section titled “Request Body required ”
object
domain
required

Fully qualified domain name to register (e.g. “example.com”)

string
>= 3 characters <= 253 characters
years

Registration period in years

integer
default: 1 >= 1 <= 10
dns_records

Optional DNS records to set on the domain after registration

Array<object>
object
type
required

DNS record type

string
Allowed values: A AAAA CNAME MX TXT SRV CAA
host

Record hostname (e.g. ”@” for root, “www”, “mail”)

string
default: @
value
required

Record value (e.g. IP address, CNAME target)

string
ttl

Time-to-live in seconds

integer
default: 3600 >= 300 <= 86400
priority

Priority for MX and SRV records

integer
<= 65535

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Domain registered successfully (synchronous)

object
transactionId
required

Unique transaction identifier

string
domain
required

The registered domain name

string
years
required

Registration period in years

integer
price_usd
required

Price paid in USD

string
expiresAt
required

Domain expiration date

string format: date-time
nameServers
required

Assigned name servers

Array<string>
dnsRecords
required

DNS records set on the domain

Array<object>
object
id
required

Unique record identifier

string
type
required

DNS record type

string
Allowed values: A AAAA CNAME MX TXT NS SRV CAA
host
required

Record hostname

string
value
required

Record value

string
ttl
required

Time-to-live in seconds

integer
distance
required

MX priority or SRV weight, null for non-MX/SRV records

integer | null

202

Section titled “202 ”

Registration accepted, processing asynchronously

object
status
required
string
Allowed value: pending
jobId
required

Job ID for polling status

string
message
required

Human-readable status message

string
poll_url
required

URL to poll for job status

string format: uri
poll_interval_ms
required

Recommended polling interval in milliseconds

integer

400

Section titled “400 ”

Validation error

object
error
required

Short error description

string
message
required

Human-readable error message

string
code
required

Machine-readable error code

string

402

Section titled “402 ”

Payment required. Retry the request with a valid x402 payment header.

object
error
required
string
Allowed value: Payment required
domain
required

The domain name

string
price_usd
required

Total price in USD (e.g. “12.99”)

string
years
required

Registration/renewal period

integer
currency
required
string
Allowed value: USDC
network
required

Payment network in CAIP-2 format

string

Headers

Section titled “Headers ”
PAYMENT-REQUIRED
string

X402 payment requirements encoded as a JSON object

409

Section titled “409 ”

Domain is unavailable for registration

object
error
required

Short error description

string
message
required

Human-readable error message

string
code
required

Machine-readable error code

string
Example
{
  "error": "Domain unavailable",
  "message": "The domain is already registered",
  "code": "DOMAIN_UNAVAILABLE"
}

429

Section titled “429 ”

Rate limit exceeded

object
error
required

Short error description

string
message
required

Human-readable error message

string
code
required

Machine-readable error code

string