rolznz/autonomous-onboarding/unhuman-domains

unhuman.domains

Programmatic domain registration for AI agents. Search, register, and manage domains via API. Pay with Bitcoin Lightning using the L402 protocol.

Overview

unhuman.domains is a domain registrar built for AI agents. All operations are performed via REST API with no KYC, no captchas, and no human intervention required. Payment and authentication use the L402 protocol (HTTP 402 + Bitcoin Lightning invoices).

Reference: https://unhuman.domains/llms.txt

Supported TLDs

com, net, org, io, dev, app, xyz, co, ai

Quick Start

1. Search for Domain Availability

curl -s "https://unhuman.domains/api/domains/search?q=myproject"

Response:

{
  "ok": true,
  "data": {
    "results": [
      { "domain": "myproject.dev", "available": true, "price": 1559 }
    ]
  }
}

Prices are in USD cents (1559 = $15.59).

2. Start Registration (Get Lightning Invoice)

curl -s -X POST "https://unhuman.domains/api/domains/myproject.dev/register" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response (HTTP 402):

{
  "error": { "code": "payment_required" },
  "macaroon": "eyJ...",
  "invoice": "lnbc1559...",
  "amountSats": 1559
}

Save the macaroon and invoice.

3. Pay the Lightning Invoice

Option A: Using Alby CLI (if you already have a wallet)

npx @getalby/cli -c ~/.alby-cli/connection-secret.key pay-invoice -i "lnbc1559..."
# Returns: preimage (hex string)

Option B: Using agent-wallet (for fully autonomous agents)

npx unhuman domains register myproject.dev --email you@example.com --wallet

Note: The --wallet flag uses agent-wallet for automatic payment. If you already have a Lightning wallet (like Alby CLI), you don't need agent-wallet—just pay the invoice manually and use the preimage in step 4.

4. Complete Registration with Payment Proof

curl -s -X POST "https://unhuman.domains/api/domains/myproject.dev/register" \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -d '{"email": "you@example.com"}'

Response:

{
  "ok": true,
  "data": {
    "domain": "myproject.dev",
    "status": "registered",
    "managementToken": "eyJhbGciOi..."
  }
}

Save the `managementToken` — it is required for all future management operations.

CLI Alternative (Recommended for Shell Access)

If you can run shell commands, the unhuman CLI handles the full flow:

# Search
npx unhuman domains search myproject
 
# Register with automatic payment (requires agent-wallet)
npx unhuman domains register myproject.dev --email you@example.com --wallet
 
# Or register without agent-wallet (manual payment)
npx unhuman domains register myproject.dev --email you@example.com
# Then pay the displayed invoice separately

Managing DNS

After registration, configure DNS records using your management token:

curl -s -X PUT "https://unhuman.domains/api/domains/myproject.dev/dns" \
  -H "Authorization: Bearer <managementToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "type": "A", "subdomain": "@", "ip": "76.76.21.21" },
      { "type": "CNAME", "subdomain": "www", "target": "cname.vercel-dns.com" }
    ]
  }'

Renewing a Domain

Renewal uses the same L402 flow as registration, plus the management token:

# Start renewal
curl -s -X POST "https://unhuman.domains/api/domains/myproject.dev/renew" \
  -H "Content-Type: application/json" \
  -H "X-Management-Token: Bearer <managementToken>" \
  -d '{"period": 1}'
 
# Pay the invoice, then complete with Authorization header
curl -s -X POST "https://unhuman.domains/api/domains/myproject.dev/renew" \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -H "X-Management-Token: Bearer <managementToken>" \
  -d '{"period": 1}'

API Reference

Authentication Summary

• None: Search, check availability, status
• L402: Registration and renewal (macaroon + preimage)
• Bearer token: All management operations (DNS, info, nameservers)
• Both L402 + Bearer: Renewal requires both payment proof and management token

Storage Recommendation

Store the management token in ~/.unhuman/tokens.json:

{
  "myproject.dev": "eyJhbGciOi..."
}

The CLI stores tokens automatically at ~/.unhuman/tokens.json.

Important Notes

• Email required: ICANN requires email verification. Use a valid email you can access (consider lnemail for anonymous email).
• Token expiry: Management tokens are valid for 1 year.
• L402 flow: The API returns HTTP 402 with a Lightning invoice. Pay it, then retry the request with Authorization: L402 <macaroon>:<preimage>.
• Agent wallet optional: The --wallet flag uses agent-wallet for autonomous payment. If you already have a Lightning wallet (Alby CLI, etc.), pay invoices manually instead.

References

• Service: https://unhuman.domains
• LLMs.txt: https://unhuman.domains/llms.txt
• CLI: npx unhuman
• L402 Protocol: HTTP 402 + Lightning invoices for API authentication