API Documentation

Overview

Agent Domain Search is an agent-first domain registration and DNS management service. Check availability, register domains, and manage DNS — all via JSON API. Pay with USDC on Base via x402. No accounts, no API keys. Your Ethereum wallet is your identity.

Free Endpoints

No authentication or payment required.

`GET /:domain`

Check availability and per-year price. Returns full details if you own the domain (with wallet auth). min_period is the minimum registration term in years (2 for .ai, 1 otherwise).

curl https://agentdomainsearch.com/example.com

{"domain":"example.com","available":true,"price":16.0,"min_period":1,"currency":"USDC"}

curl https://agentdomainsearch.com/example.ai

{"domain":"example.ai","available":true,"price":84.0,"min_period":2,"currency":"USDC"}

`GET /suggest?q=keyword`

Domain name suggestions based on a keyword.

curl https://agentdomainsearch.com/suggest?q=myproject

`GET /:domain/price`

Pricing for 1–10 year registrations.

curl https://agentdomainsearch.com/example.com/price

Paid Endpoints (x402)

These return 402 Payment Required with payment details. Your agent pays with USDC on Base, then retries.

`POST /:domain`

`POST /:domain/renew`

Renew a domain you own.

Authentication

Sign the message agentdomainsearch.com:<unix-timestamp> using EIP-191 personal_sign. The token is the timestamp and signature joined with a dot. Tokens are valid for 5 minutes.

Token format

<unix-timestamp>.<130-hex-char-signature>

Signing (JavaScript / ethers.js)

const ts = Math.floor(Date.now() / 1000);
const sig = (await wallet.signMessage("agentdomainsearch.com:" + ts)).slice(2);
const token = ts + "." + sig;

Signing (Python / web3.py)

import time
from web3 import Web3
ts = int(time.time())
msg = f"agentdomainsearch.com:{ts}"
sig = w3.eth.account.sign_message(encode_defunct(text=msg), private_key=key).signature.hex()[2:]
token = f"{ts}.{sig}"

Sending

Authorization: Bearer <token>
# or
Authorization: Basic base64("0x:<token>")

Authenticated Endpoints

Endpoint	Description
`GET /domains`	List domains owned by your wallet
`PUT /:domain/ns`	Update nameservers
`GET /:domain/dns`	View DNS zone records
`PUT /:domain/dns`	Set DNS records
`DELETE /:domain/dns`	Delete DNS zone
`PUT /:domain/lock`	Lock or unlock domain
`PUT /:domain/contacts`	Update registrant contacts
`POST /:domain/verify`	Resend ICANN verification email
`GET /:domain/transfer`	Get EPP auth code for transfer out

Transferring a Domain Out

To transfer your domain to another registrar:

Set up DNS at your new provider first. DNS zones hosted here become inaccessible after transfer. If your domain uses our nameservers (ns1.systemdns.com), it will stop resolving immediately after transfer unless you switch nameservers first.
Update nameservers: PUT /:domain/ns
Unlock the domain: PUT /:domain/lock with {"locked": false}
Get the auth code: GET /:domain/transfer
Give the auth code to your new registrar and approve the confirmation email.

Pricing & Domain Lifecycle

All prices are in USDC (1:1 with USD). Markup is applied per year — total = price × period. WHOIS privacy is always included at no extra cost.

Some TLDs require a minimum multi-year registration (e.g. .ai requires 2 years). The min_period field in GET /:domain and GET /:domain/price tells you the minimum; POST /:domain defaults period to that value and rejects lower values with 400.

Event	Timing	Action Required
Registration	Immediate	~$16 USDC for .com (1-year min). ~$84/year for .ai (2-year min).
ICANN verification	Within 15 days	Click email link or domain is suspended
Renewal window	Before expiry date	POST /:domain/renew with x402 payment
Expiry + grace period	0–40 days after expiry	Domain stops resolving after 3 days. Can still renew.
Redemption period	40–70 days after expiry	Recovery possible but may incur additional fees.
Deletion	~70 days after expiry	Domain released to public. Cannot be recovered.
Transfer out	Any time (60+ days after registration)	GET /:domain/transfer for auth code. Set up DNS at new registrar first.

Identity

Your Ethereum wallet address is your identity. The address that pays for a domain owns it. Management endpoints verify ownership via EIP-191 signatures. No accounts, no passwords, no email/password auth.

Terms & Privacy