# ClawDaddy.app 🦞

> The World's #1 AI-Friendly Domain Registrar
> No CAPTCHAs. No signup. Just claws.

## 🦞 LOBSTER LAUNCH SPECIAL 🦞

**DOMAINS AT COST - WE MAKE $0!**

For a limited time, ClawDaddy charges NO profit margin on domain registrations.
You pay the wholesale price + payment processing fees. We make $0. We're insane lobsters.

- No profit margin
- No hidden costs
- Just wholesale domain pricing + Stripe fees (2.9% + $0.30)

## Quick Start

Check a domain:
```
GET https://clawdaddy.app/api/lookup/example.com
```

Brainstorm available domains:
```
POST https://clawdaddy.app/api/brainstorm
```

Purchase a domain:
```
POST https://clawdaddy.app/api/purchase/example.com
→ Returns Stripe checkout URL
```

Manage your domain:
```
GET https://clawdaddy.app/api/manage/example.com
Authorization: Bearer $CLAWDADDY_TOKEN
```

---

## 1. Domain Lookup API

### Check Availability

| Route | Format | Content-Type |
|-------|--------|--------------|
| `/api/lookup/{domain}` | JSON | application/json |
| `/api/lookup/{domain}?format=txt` | TXT | text/plain |
| `/lookup/{domain}` | HTML | text/html |

### JSON Response

```
GET /api/lookup/example.com
```

```json
{
  "fqdn": "example.com",
  "available": true,
  "status": "available",
  "premium": false,
  "price": {
    "amount": 12.99,
    "currency": "USD",
    "period": "year"
  },
  "checked_at": "2026-01-15T10:30:00.000Z",
  "source": "namecom",
  "cache": { "hit": false, "ttl_seconds": 120 }
}
```

### Status Values

| Status | available | Meaning |
|--------|-----------|---------|
| `available` | `true` | Can be registered |
| `registered` | `false` | Already taken |
| `unknown` | `false` | Could not determine |

---

## 2. Domain Brainstorm API

Use this when you need a list of **available** domains fast.

```
POST /api/brainstorm
```

Example request:
```json
{
  "prompt": "AI tool for async standups",
  "count": 8,
  "mode": "balanced",
  "max_price": 30,
  "tlds": ["com", "io", "ai"],
  "style": "brandable",
  "must_include": ["standup"]
}
```

Modes:
- `fast`: cache only (lowest latency)
- `balanced`: cache + live Name.com search
- `deep`: adds generated checks for more creativity

---

## 3. Domain Purchase API

### Step 1: Get Quote

```
GET /api/purchase/example.com/quote
```

```json
{
  "domain": "example.com",
  "available": true,
  "priceUsd": 12.99,
  "marginUsd": 0.70,
  "totalUsd": 13.69,
  "validUntil": "2026-01-15T10:35:00.000Z"
}
```

Note: During Lobster Launch, `marginUsd` only covers Stripe fees (2.9% + $0.30). We make $0!

### Step 2: Initiate Purchase

```
POST /api/purchase/example.com
```

Returns a Stripe checkout URL:
```json
{
  "method": "stripe",
  "checkoutUrl": "https://checkout.stripe.com/...",
  "sessionId": "cs_xxx",
  "quote": { ... }
}
```

**For AI Agents:** Direct your user to the `checkoutUrl` to complete payment.

### Step 3: After Payment

After successful payment, the user receives:
- Domain registered immediately
- Management token displayed on success page
- Email confirmation with token backup

Success page provides instructions to add token to environment:
```
CLAWDADDY_TOKEN=clwd_abc123xyz...
```

---

## 4. Domain Management API

All management endpoints require the `Authorization` header:
```
Authorization: Bearer $CLAWDADDY_TOKEN
```

**Setting up the token for your agent:**

Add to `~/.openclaw/.env` or your project's `.env` file:
```
CLAWDADDY_TOKEN=clwd_your_management_token
```

Your agent can then use `$CLAWDADDY_TOKEN` in API calls.

### Get Domain Overview

```
GET /api/manage/{domain}
```

```json
{
  "domain": "example.com",
  "purchasedAt": "2026-01-15T10:30:00.000Z",
  "expiresAt": "2027-01-15T10:30:00.000Z",
  "nameservers": ["ns1.name.com", "ns2.name.com"],
  "settings": {
    "locked": true,
    "autorenewEnabled": false,
    "privacyEnabled": true
  }
}
```

### DNS Records

**List all records:**
```
GET /api/manage/{domain}/dns
```

**Create a record:**
```
POST /api/manage/{domain}/dns
Content-Type: application/json

{
  "host": "@",
  "type": "A",
  "answer": "1.2.3.4",
  "ttl": 300
}
```

**Delete a record:**
```
DELETE /api/manage/{domain}/dns?id=123
```

Supported record types: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV`

### Nameservers

**Get current nameservers:**
```
GET /api/manage/{domain}/nameservers
```

**Update nameservers:**
```
PUT /api/manage/{domain}/nameservers
Content-Type: application/json

{
  "nameservers": [
    "ns1.cloudflare.com",
    "ns2.cloudflare.com"
  ]
}
```

Common nameserver configurations:
- Cloudflare: `ns1.cloudflare.com`, `ns2.cloudflare.com`
- Vercel: `ns1.vercel-dns.com`, `ns2.vercel-dns.com`
- AWS Route53: Check your hosted zone

### Domain Settings

**Get settings:**
```
GET /api/manage/{domain}/settings
```

**Update settings:**
```
PATCH /api/manage/{domain}/settings
Content-Type: application/json

{
  "locked": false,
  "autorenewEnabled": true
}
```

### Transfer Out

**Get auth code:**
```
GET /api/manage/{domain}/transfer
```

**Prepare for transfer (unlock + get code):**
```
POST /api/manage/{domain}/transfer
```

Note: Domains cannot be transferred within 60 days of registration (ICANN policy).

---

## 4. Token Recovery

Lost your management token? Request a new one via email:

**IMPORTANT:** Token recovery generates a NEW token. Your old token will be invalidated.

```
POST /api/recover
Content-Type: application/json

{
  "email": "you@example.com",
  "domain": "example.com"  // Optional - omit to recover all domains
}
```

Response is always the same (to prevent email enumeration):
```json
{
  "success": true,
  "message": "If we have domains registered with this email, you'll receive an email shortly."
}
```

Rate limit: 5 requests per 5 minutes per IP.

---

## Complete Agent Workflow

```
1. CHECK AVAILABILITY
   GET /api/lookup/coolstartup.com
   → available: true, price: $12.99

2. GET QUOTE
   GET /api/purchase/coolstartup.com/quote
   → totalUsd: $12.99 (Lobster Launch: $0 markup!)

3. INITIATE PURCHASE
   POST /api/purchase/coolstartup.com
   → checkoutUrl: "https://checkout.stripe.com/..."
   → Direct user to complete payment

4. USER COMPLETES PAYMENT
   → Token shown on success page
   → User adds to .env: CLAWDADDY_TOKEN=clwd_abc123...

5. CONFIGURE DNS
   POST /api/manage/coolstartup.com/dns
   Authorization: Bearer $CLAWDADDY_TOKEN
   {"host": "@", "type": "A", "answer": "1.2.3.4"}

6. OR POINT TO CLOUDFLARE
   PUT /api/manage/coolstartup.com/nameservers
   Authorization: Bearer $CLAWDADDY_TOKEN
   {"nameservers": ["ns1.cloudflare.com", "ns2.cloudflare.com"]}
```

---

## Error Responses

All errors return JSON:
```json
{
  "error": "Description of what went wrong",
  "details": "Additional context if available"
}
```

Common status codes:
- `400` - Bad request (invalid input)
- `401` - Unauthorized (missing/invalid token)
- `404` - Domain not found
- `429` - Rate limited
- `500` - Server error

---

## Human Dashboard

Users can also manage domains via web UI at:
```
https://clawdaddy.app/manage
```

Enter the management token to access DNS, nameservers, and settings.

---

Built with 🦞 for AI agents everywhere.
https://clawdaddy.app