Skip to content
Bloomfilter Bloomfilter

Registering a Domain

The full flow

Section titled “The full flow”

  1. Search for availability

    Terminal window
    curl "https://api.bloomfilter.xyz/domains/search?query=myproject&tlds=com,io,xyz"
    {
      "query": "myproject",
      "results": [
        { "domain": "myproject.com", "tld": "com", "available": false },
        { "domain": "myproject.io", "tld": "io", "available": true },
        { "domain": "myproject.xyz", "tld": "xyz", "available": true }
      ]
    }

  2. Check pricing (optional)

    Terminal window
    curl https://api.bloomfilter.xyz/domains/pricing/io
    {
      "tld": "io",
      "registration_price_usd": "34.99",
      "renewal_price_usd": "34.99",
      "transfer_price_usd": "34.99",
      "currency": "USDC"
    }

  3. Register the domain

    Terminal window
    curl -X POST https://api.bloomfilter.xyz/domains/register \
      -H "Content-Type: application/json" \
      -d '{"domain": "myproject.io", "years": 1}'

    The first request returns 402 Payment Required. If using @x402/axios or the MCP server, payment is handled automatically. See x402 Payment Flow for manual implementation.

    Success response (201):

    {
      "transactionId": "01JMXYZ...",
      "domain": "myproject.io",
      "status": "active",
      "years": 1,
      "price_usd": "34.99",
      "registeredAt": "2026-02-21T12:00:00Z",
      "expiresAt": "2027-02-21T00:00:00Z",
      "nameservers": ["ns1.bloomfilter.xyz", "ns2.bloomfilter.xyz"],
      "dnsRecords": []
    }

  4. Handle async registration (if needed)

    Some registrations return 202 Accepted instead. Poll the job status:

    Terminal window
    curl https://api.bloomfilter.xyz/domains/status/01JMXYZ...

    See Async Provisioning for details.

Registration with DNS records

Section titled “Registration with DNS records”

You can pre-configure DNS records during registration:

Terminal window
curl -X POST https://api.bloomfilter.xyz/domains/register \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "myproject.io",
    "years": 1,
    "dns_records": [
      { "type": "A", "host": "@", "value": "76.76.21.21" },
      { "type": "CNAME", "host": "www", "value": "myproject.io" },
      { "type": "MX", "host": "@", "value": "mail.example.com", "priority": 10 }
    ]
  }'

Multi-year registration

Section titled “Multi-year registration”

Register for up to 10 years at once:

Terminal window
curl -X POST https://api.bloomfilter.xyz/domains/register \
  -H "Content-Type: application/json" \
  -d '{"domain": "myproject.io", "years": 3}'

The total price scales linearly: price_per_year × years.

Domain info

Section titled “Domain info”

Check any domain’s status (no auth required):

Terminal window
curl https://api.bloomfilter.xyz/domains/myproject.io
{
  "domain": "myproject.io",
  "tld": "io",
  "status": "active",
  "registeredAt": "2026-02-21T12:00:00Z",
  "expiresAt": "2027-02-21T00:00:00Z",
  "registrar": "Bloomfilter",
  "nameservers": ["ns1.bloomfilter.xyz", "ns2.bloomfilter.xyz"],
  "autoRenew": false,
  "whoisPrivacy": true
}

Common errors

Section titled “Common errors”
ErrorCodeMeaning
Domain unavailableDOMAIN_UNAVAILABLE (409)Domain is already registered
TLD not supportedTLD_NOT_SUPPORTED (400)We don’t support this TLD
Insufficient fundsPAYMENT_INSUFFICIENT (402)Wallet doesn’t have enough USDC
Rate limitedRATE_LIMITED (429)Max 10 registrations per day