# Agent Domain Search
> Agent-first domain registration and DNS management. Check availability, register domains, and manage DNS via JSON API. Pay with USDC on Base via x402. No accounts, no API keys — wallet signatures and inline payments only.

## Quick Start
1. Check availability: GET https://agentdomainsearch.com/example.com
2. Get suggestions: GET https://agentdomainsearch.com/suggest?q=myproject
3. Register: POST https://agentdomainsearch.com/example.com (x402 USDC payment)
4. Manage DNS: PUT https://agentdomainsearch.com/example.com/dns (wallet auth)

## Authentication
Sign "agentdomainsearch.com:<unix-timestamp>" with EIP-191 personal_sign.
Token: <timestamp>.<130-hex-char-signature> (strip 0x prefix). Valid 5 minutes.
Send as: Authorization: Bearer <token>

## Payment (x402)
Network: base | Asset: USDC | Facilitator: https://api.cdp.coinbase.com/platform/v2/x402
Manifest: https://agentdomainsearch.com/.well-known/x402.json

## Pricing
`price` in check/price responses is per-year retail (USDC). Total = `price × period`.
Some TLDs require multi-year registration; `min_period` in responses indicates the minimum (e.g. 2 for .ai). POST /:domain defaults `period` to `min_period` and rejects lower values with 400.

## Example: Register a domain
Two-step x402 flow. First call returns 402 + payment details; sign the EIP-3009 authorization with your wallet, base64-encode the x402 payload, then retry with the PAYMENT-SIGNATURE header.

curl -X POST https://agentdomainsearch.com/example.com \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64(JSON.stringify({x402Version:2,scheme:"exact",network:"base",payload:{signature,authorization:{from,to,value,validAfter,validBefore,nonce}}}))>" \
  -d '{
    "contacts": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "org_name": "Analytical Engines Ltd",
      "email": "ada@example.com",
      "phone": "+1.5555551234",
      "address1": "123 Main St",
      "city": "London",
      "state": "CA",
      "postal_code": "94000",
      "country": "US"
    },
    "period": 1,
    "nameservers": ["ns1.systemdns.com", "ns2.systemdns.com"]
  }'

Response (201): { "domain": "example.com", "registered": true, "expires": "2027-04-22", "owner": "0x...", "verification_required": true, "verification_email": "ada@example.com" }
The wallet that paid (x402 `from` address) becomes the owner. WHOIS privacy is always on. `nameservers` is optional; omit to use OpenSRS managed DNS. `period` defaults to the TLD's `min_period` (2 for .ai, 1 otherwise).

## Endpoints
GET  /:domain              Check availability + price (free)
GET  /:domain/price        Pricing 1-10 years (free)
GET  /suggest?q=keyword    Domain name suggestions (free)
POST /:domain              Register domain (x402 USDC)
POST /:domain/renew        Renew domain (x402 USDC)
GET  /domains              List your domains (wallet auth)
PUT  /:domain/ns           Update nameservers (wallet auth)
GET  /:domain/dns          View DNS records (wallet auth)
PUT  /:domain/dns          Set DNS records (wallet auth)
DELETE /:domain/dns        Delete DNS zone (wallet auth)
PUT  /:domain/lock         Lock/unlock domain (wallet auth)
PUT  /:domain/contacts     Update contacts (wallet auth)
POST /:domain/verify       Resend ICANN verification (wallet auth)
GET  /:domain/transfer      Get EPP auth code for transfer out (wallet auth)

## Docs
- [API Documentation](https://agentdomainsearch.com/docs)
- [Terms & Privacy](https://agentdomainsearch.com/terms)
- [x402 Manifest](https://agentdomainsearch.com/.well-known/x402.json)