--- name: nameclaw-domains description: "Search, register, and manage domain names via the NameClaw API — check availability, register with x402 USDC payments on Base, configure DNS records, manage WHOIS privacy, and update nameservers." --- # NameClaw Domains API NameClaw is a domain registrar with a REST API at `https://api.nameclaw.org`. Domains are purchased with USDC on Base via the x402 payment protocol. Authentication uses Sign-In with Ethereum (SIWE). ## Base URL ``` https://api.nameclaw.org ``` ## Core Concepts - **x402 payment**: Registration and renewal endpoints return HTTP 402 with a `payment-required` header. The x402 client signs a USDC payment on Base and retries the request with a payment proof header. Payment is in USDC (6 decimals) on Base mainnet (chain ID 8453). - **SIWE authentication**: Users sign in by signing an Ethereum message. The flow is: get nonce → sign SIWE message → verify signature → receive JWT. - **JWT tokens**: After SIWE verification, all authenticated endpoints require `Authorization: Bearer `. Tokens expire in 24 hours. - **Pricing tiers**: Domains are classified into Standard ($12), Premium ($35), and Ultra ($75) based on TLD wholesale cost and market value. - **WHOIS privacy**: All domains include WHOIS privacy. TLDs that don't support privacy are not offered. - **Pay-to address**: `0x5bc8ba1c9dcab17d3eca662a6abd0ee42cf71be9` (USDC on Base, network `eip155:8453`). ## Authentication Flow ### 1. Get a nonce ``` GET /auth/nonce ``` Response: ```json { "nonce": "47b14cf495444a195011ad22b1d2a6c6", "expiresAt": "2026-02-25T02:00:31.759Z" } ``` Nonce expires in 5 minutes. ### 2. Sign SIWE message Construct a SIWE message with the nonce and sign it with the wallet: ``` nameclaw.org wants you to sign in with your Ethereum account: 0xYourAddress Sign in to NameClaw URI: https://nameclaw.org Version: 1 Chain ID: 8453 Nonce: 47b14cf495444a195011ad22b1d2a6c6 Issued At: 2026-02-25T01:55:31.759Z ``` ### 3. Verify signature ``` POST /auth/verify Content-Type: application/json { "message": "", "signature": "0x..." } ``` Response: ```json { "token": "eyJhbGciOiJIUzI1NiIs...", "address": "0xce12ba871f90fa284491c17a11b434c1c5cd5086" } ``` Use the token in all authenticated requests: ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ``` ## Workflows ### Search for domains ``` GET /domains/search?query=myproject&tlds=com,net,org,io,dev,app,co,ai ``` Response: ```json { "results": [ { "domain": "myproject.com", "available": true, "tier": "premium", "price": 35 }, { "domain": "myproject.org", "available": true, "tier": "standard", "price": 12 }, { "domain": "myproject.ai", "available": false, "tier": "ultra", "price": 75 } ] } ``` For exact domain checks: ``` GET /domains/check?domains=myproject.com,myproject.io,coolname.dev ``` ### Check pricing ``` GET /domains/pricing ``` Response: ```json { "tiers": { "standard": 12, "premium": 35, "ultra": 75 }, "tlds": [ { "tld": "com", "registration": 10.79, "renewal": 10.79, "tier": "standard", "price": 12 }, { "tld": "io", "registration": 32.99, "renewal": 32.99, "tier": "premium", "price": 35 }, { "tld": "ai", "registration": 68.99, "renewal": 68.99, "tier": "ultra", "price": 75 } ] } ``` ### Register a domain Registration requires authentication and x402 payment. The endpoint returns 402 first — the x402 client handles payment automatically. ``` POST /domains/register/{tier} Authorization: Bearer Content-Type: application/json { "domain": "myproject.org", "years": 1 } ``` Tier must match the domain's TLD tier: - `POST /domains/register/standard` — $12 USDC (e.g., .com, .net, .org, .xyz) - `POST /domains/register/premium` — $35 USDC (e.g., .io, .dev, .app, .co) - `POST /domains/register/ultra` — $75 USDC (e.g., .ai) Response (201): ```json { "domain": "myproject.org", "owner": "0xce12ba871f90fa284491c17a11b434c1c5cd5086", "expiresAt": "2027-02-25T00:00:00.000Z", "priceTier": "standard" } ``` ### List owned domains ``` GET /domains Authorization: Bearer ``` Response: ```json { "domains": [ { "name": "myproject.org", "expiresAt": "2027-02-25T00:00:00.000Z", "priceTier": "standard", "privacyEnabled": true, "autoRenew": false } ] } ``` ### Get domain details ``` GET /domains/{domain} Authorization: Bearer ``` Response: ```json { "domain": "myproject.org", "status": "Active", "createdDate": "2026-02-25", "expiresDate": "2027-02-25", "locked": true, "private": true, "autoRenew": false, "nameservers": ["NS1.DNSOWL.COM", "NS2.DNSOWL.COM", "NS3.DNSOWL.COM"], "owner": "0xce12ba871f90fa284491c17a11b434c1c5cd5086", "priceTier": "standard" } ``` ### Renew a domain Requires authentication, domain ownership, and x402 payment. ``` POST /domains/{domain}/renew/{tier} Authorization: Bearer Content-Type: application/json { "years": 1 } ``` Tier must match the domain's original tier. Response: ```json { "domain": "myproject.org", "expiresAt": "2028-02-25" } ``` ### Manage DNS records **List records:** ``` GET /domains/{domain}/dns Authorization: Bearer ``` Response: ```json { "records": [ { "recordId": "abc123", "type": "A", "host": "", "value": "76.76.21.21", "ttl": 3600 }, { "recordId": "def456", "type": "CNAME", "host": "www", "value": "myproject.org", "ttl": 3600 } ] } ``` **Add a record:** ``` POST /domains/{domain}/dns Authorization: Bearer Content-Type: application/json { "type": "A", "host": "", "value": "76.76.21.21", "ttl": 3600 } ``` Supported types: A, AAAA, CNAME, MX, TXT, SRV, CAA. MX records accept an optional `distance` field. **Update a record:** ``` PUT /domains/{domain}/dns/{recordId} Authorization: Bearer Content-Type: application/json { "host": "", "value": "1.2.3.4", "ttl": 3600 } ``` **Delete a record:** ``` DELETE /domains/{domain}/dns/{recordId} Authorization: Bearer ``` Returns 204 No Content. ### Toggle WHOIS privacy ``` PUT /domains/{domain}/privacy Authorization: Bearer Content-Type: application/json { "enabled": true } ``` ### Update nameservers ``` PUT /domains/{domain}/nameservers Authorization: Bearer Content-Type: application/json { "nameservers": ["ns1.example.com", "ns2.example.com"] } ``` Accepts 1–13 nameservers. ## x402 Payment Details When calling a payment-protected endpoint, the server responds with: ``` HTTP/1.1 402 Payment Required payment-required: ``` Decoded payload: ```json { "x402Version": 2, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "12000000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x5bc8ba1c9dcab17d3eca662a6abd0ee42cf71be9", "maxTimeoutSeconds": 300 } ] } ``` - **Asset**: USDC on Base (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, 6 decimals) - **Amount**: In smallest unit (e.g., `12000000` = $12.00 USDC) - **Network**: Base mainnet (`eip155:8453`) The x402 client libraries handle 402 responses, wallet signing, and payment retry automatically. See the Node.js example below. ## Node.js / Agent Integration Install dependencies: ```bash npm install viem @x402/core @x402/evm @x402/fetch ``` Complete working example: ```typescript import { createWalletClient, http, publicActions } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { base } from "viem/chains"; import { x402Client } from "@x402/core/client"; import { registerExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { createSiweMessage } from "viem/siwe"; const API = "https://api.nameclaw.org"; // 1. Setup wallet (Base mainnet) const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY"); const signer = createWalletClient({ account, chain: base, transport: http(), }).extend(publicActions); // 2. Setup x402 payment client const client = new x402Client(); registerExactEvmScheme(client, { signer }); const x402Fetch = wrapFetchWithPayment(fetch, client); // 3. SIWE authentication const { nonce } = await fetch(`${API}/auth/nonce`).then(r => r.json()); const message = createSiweMessage({ domain: "nameclaw.org", address: account.address, statement: "Sign in to NameClaw", uri: "https://nameclaw.org", version: "1", chainId: 8453, nonce, }); const signature = await signer.signMessage({ account, message }); const { token } = await fetch(`${API}/auth/verify`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ message, signature }), }).then(r => r.json()); // 4. Search for domains (no auth needed) const search = await fetch( `${API}/domains/search?query=myproject&tlds=com,org,io` ).then(r => r.json()); // 5. Register domain (x402 handles 402 → USDC payment → retry automatically) const result = await x402Fetch(`${API}/domains/register/standard`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", }, body: JSON.stringify({ domain: "myproject.org", years: 1 }), }).then(r => r.json()); // 6. Configure DNS await fetch(`${API}/domains/myproject.org/dns`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "A", host: "", value: "76.76.21.21", ttl: 3600 }), }); ``` **Common pitfalls:** - Import `x402Client` from `@x402/core/client` and `registerExactEvmScheme` from `@x402/evm/exact/client` — these are subpath exports, not top-level. - Pass the `x402Client` instance directly to `wrapFetchWithPayment`. Do **not** use `x402HTTPClient` — that is for remote HTTP facilitators (server-side verification), not local wallet signing. - `createWalletClient({...}).extend(publicActions)` satisfies the signer interface directly — no manual wrapping needed. `toClientEvmSigner()` also works in Node.js but is optional. - Only use `x402Fetch` for payment-protected endpoints (register, renew). Regular endpoints use normal `fetch`. ## API Reference | Method | Path | Auth | x402 | Description | |--------|------|------|------|-------------| | GET | `/health` | No | No | Health check | | GET | `/auth/nonce` | No | No | Get SIWE nonce | | POST | `/auth/verify` | No | No | Verify SIWE signature, get JWT | | GET | `/domains/search` | No | No | Search domains by keyword | | GET | `/domains/check` | No | No | Check exact domain availability | | GET | `/domains/pricing` | No | No | Get tier and TLD pricing | | GET | `/domains` | Yes | No | List owned domains | | GET | `/domains/:domain` | Yes | No | Get domain details | | POST | `/domains/register/standard` | Yes | $12 | Register standard domain | | POST | `/domains/register/premium` | Yes | $35 | Register premium domain | | POST | `/domains/register/ultra` | Yes | $75 | Register ultra domain | | POST | `/domains/:domain/renew/standard` | Yes | $12 | Renew standard domain | | POST | `/domains/:domain/renew/premium` | Yes | $35 | Renew premium domain | | POST | `/domains/:domain/renew/ultra` | Yes | $75 | Renew ultra domain | | PUT | `/domains/:domain/privacy` | Yes | No | Toggle WHOIS privacy | | PUT | `/domains/:domain/nameservers` | Yes | No | Update nameservers | | GET | `/domains/:domain/dns` | Yes | No | List DNS records | | POST | `/domains/:domain/dns` | Yes | No | Add DNS record | | PUT | `/domains/:domain/dns/:recordId` | Yes | No | Update DNS record | | DELETE | `/domains/:domain/dns/:recordId` | Yes | No | Delete DNS record | ## Rate Limits 60 requests per 60 seconds per IP. ## Error Format ```json { "error": { "code": "VALIDATION_ERROR", "message": "query parameter is required" } } ``` Error codes: `VALIDATION_ERROR`, `AUTH_ERROR`, `FORBIDDEN`, `NOT_FOUND`, `INTERNAL_ERROR`. ## Example: Full Registration Flow ```bash # 1. Get nonce NONCE=$(curl -s https://api.nameclaw.org/auth/nonce | jq -r '.nonce') # 2. Sign SIWE message with wallet (app-specific) # 3. Verify and get token TOKEN=$(curl -s -X POST https://api.nameclaw.org/auth/verify \ -H 'Content-Type: application/json' \ -d '{"message":"...","signature":"0x..."}' | jq -r '.token') # 4. Search for available domains curl -s "https://api.nameclaw.org/domains/search?query=myproject&tlds=com,org,io" \ | jq '.results[] | select(.available)' # 5. Register (x402 payment handled by client library) curl -s -X POST https://api.nameclaw.org/domains/register/standard \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"domain":"myproject.org","years":1}' # 6. Configure DNS curl -s -X POST https://api.nameclaw.org/domains/myproject.org/dns \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"type":"A","host":"","value":"76.76.21.21","ttl":3600}' curl -s -X POST https://api.nameclaw.org/domains/myproject.org/dns \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"type":"CNAME","host":"www","value":"myproject.org","ttl":3600}' ``` ## Panel The web panel at [panel.nameclaw.org](https://panel.nameclaw.org) provides a UI for all of the above: wallet sign-in, domain search, registration, DNS editor, and transaction history.