# unhuman.domains

> The domain registrar built for AI agents. Search, register, and manage domains via API. Pay with Bitcoin Lightning.

## Overview

unhuman.domains is a programmatic domain registration service. All operations are performed via REST API. Payment uses the L402 protocol (HTTP 402 + Bitcoin Lightning Network invoices). No API keys or accounts are needed to get started — payment itself is the authentication for registration.

Base URL: https://unhuman.domains

## Supported TLDs

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

Prices are in USD cents. The `.ai` TLD requires a 2-year minimum registration period; all others default to 1 year.

## Quick Start: CLI (recommended for agents with shell access)

If you can run commands, the `unhuman` CLI handles the entire flow — search, payment, registration — in one step:

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

The `--wallet` flag pays automatically via [agent-wallet](https://docs.moneydevkit.com/agent-wallet), a self-custodial Bitcoin Lightning wallet built for AI agents. No human interaction needed.

See the full CLI reference at the bottom of this document.

## Quick Start: REST API

### Step 1 — Search for availability

```
GET /api/domains/search?q=myproject
```

Optional: filter TLDs with `&tld=com,dev,io`

Response:

```json
{
  "ok": true,
  "data": {
    "query": "myproject",
    "results": [
      { "domain": "myproject.com", "tld": "com", "available": true, "price": 1319, "premium": false },
      { "domain": "myproject.dev", "tld": "dev", "available": true, "price": 1559, "premium": false }
    ],
    "currency": "USD",
    "priceUnit": "cents"
  }
}
```

Pick a domain where `available` is `true`.

### Step 2 — Start registration (get a Lightning invoice)

```
POST /api/domains/myproject.dev/register
Content-Type: application/json

{ "email": "you@example.com" }
```

The `email` field is **required**. ICANN sends a verification link to this address after registration — failure to verify will result in domain suspension. It also enables token recovery if you lose your management token.

Response (HTTP 402):

```json
{
  "error": { "code": "payment_required", "message": "Payment required" },
  "macaroon": "eyJ...",
  "invoice": "lnbc1559...",
  "paymentHash": "abc123...",
  "amountSats": 1559,
  "expiresAt": 1234567890
}
```

Save the `macaroon` and `invoice` values (both are top-level fields).

### Step 3 — Pay the Lightning invoice

Pay the BOLT11 invoice (`lnbc...`) using any Lightning wallet. After payment, your wallet will provide a **preimage** (hex string) as proof of payment.

### Step 4 — Complete registration with payment proof

Replay the same POST, adding the `Authorization` header:

```
POST /api/domains/myproject.dev/register
Content-Type: application/json
Authorization: L402 <macaroon>:<preimage>

{ "email": "you@example.com" }
```

Replace `<macaroon>` with the macaroon from step 2 and `<preimage>` with the preimage from step 3.

Response (HTTP 200):

```json
{
  "ok": true,
  "data": {
    "domain": "myproject.dev",
    "orderId": "12345678",
    "status": "registered",
    "period": 1,
    "managementToken": "eyJhbGciOi...",
    "email": "you@example.com",
    "whoisPrivacy": true,
    "management": {
      "dns": "/api/domains/myproject.dev/dns",
      "info": "/api/domains/myproject.dev/info",
      "nameservers": "/api/domains/myproject.dev/nameservers",
      "renew": "/api/domains/myproject.dev/renew",
      "recover": "/api/domains/recover"
    }
  }
}
```

Save your `managementToken` — it is a JWT valid for 1 year and is required for all future management operations on this domain.

## API Reference

### Public Endpoints (no auth)

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/domains | API discovery and documentation |
| GET | /api/domains/search?q={query} | Search domain availability across TLDs |
| GET | /api/domains/{domain}/register | Check availability and pricing for a specific domain |
| GET | /api/domains/status/{domain} | Check registration status |

### Payment Endpoints (L402 auth)

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/domains/{domain}/register | Register a domain (402 flow) |
| POST | /api/domains/{domain}/renew | Renew a domain (402 flow + management token) |

### Management Endpoints (Bearer token auth)

All management endpoints require:

```
Authorization: Bearer <managementToken>
```

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/domains/{domain}/info | Domain info (expiry, nameservers, status) |
| GET | /api/domains/{domain}/dns | Get DNS records |
| PUT | /api/domains/{domain}/dns | Set DNS records (replaces entire zone) |
| PUT | /api/domains/{domain}/nameservers | Update nameservers (custom nameservers disable DNS management) |

### Recovery Endpoints (no auth)

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/domains/recover | Request a recovery code via email |
| POST | /api/domains/recover/confirm | Confirm code, receive new management token |

## Managing DNS

After registration, set DNS records (requires OpenSRS default nameservers):

```
PUT /api/domains/myproject.dev/dns
Authorization: Bearer <managementToken>
Content-Type: application/json

{
  "records": [
    { "type": "A", "subdomain": "@", "ip": "76.76.21.21" },
    { "type": "CNAME", "subdomain": "www", "target": "cname.vercel-dns.com" },
    { "type": "TXT", "subdomain": "@", "value": "v=spf1 include:_spf.google.com ~all" },
    { "type": "MX", "subdomain": "@", "target": "mail.example.com", "priority": 10 }
  ]
}
```

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

Note: PUT replaces the entire DNS zone. Always include all records you want to keep.

If you want to manage DNS via this API, ensure the domain uses the OpenSRS default nameservers:

- `ns1.systemdns.com`
- `ns2.systemdns.com`
- `ns3.systemdns.com`

Switch back to OpenSRS defaults (re-enables DNS management):

```
PUT /api/domains/myproject.dev/nameservers
Authorization: Bearer <managementToken>
Content-Type: application/json

{ "useDefault": true }
```

## Updating Nameservers

To delegate to external nameservers:

```
PUT /api/domains/myproject.dev/nameservers
Authorization: Bearer <managementToken>
Content-Type: application/json

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

Requires at least 2 nameservers.

## Renewing a Domain

Renewal uses the same L402 two-step payment flow as registration, but also requires your management token in the `X-Management-Token` header:

```
POST /api/domains/myproject.dev/renew
Content-Type: application/json
X-Management-Token: Bearer <managementToken>

{ "period": 1 }
```

This returns a 402 with a Lightning invoice. After paying, retry with the payment proof:

```
POST /api/domains/myproject.dev/renew
Content-Type: application/json
Authorization: L402 <macaroon>:<preimage>
X-Management-Token: Bearer <managementToken>

{ "period": 1 }
```

## Recovering a Lost Management Token

If you registered with an email, you can recover your token:

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

{ "domain": "myproject.dev", "email": "you@example.com" }
```

Then confirm with the 6-digit code sent to your email:

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

{ "domain": "myproject.dev", "email": "you@example.com", "code": "123456" }
```

This returns a new `managementToken` and revokes the previous one.

## Authentication Summary

- **None**: Search, check availability, status, API discovery, recovery
- **L402**: Domain registration and renewal (HTTP 402 + Lightning invoice + preimage)
- **Bearer token**: All domain management (DNS, nameservers, info)
- **Both L402 + Bearer**: Renewal requires payment proof AND management token

## Error Format

All errors follow:

```json
{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

Common codes: `INVALID_DOMAIN`, `UNSUPPORTED_TLD`, `UNAUTHORIZED`, `TOKEN_EXPIRED`, `FORBIDDEN`, `DOMAIN_NOT_FOUND`, `payment_required`.

## CLI

If you can run shell commands, the `unhuman` CLI is the fastest way to interact with this API.

Install and run (no global install needed):

```
npx unhuman domains search myproject
```

### Commands

| Command | Description |
|---------|-------------|
| `unhuman domains search <query>` | Search domain availability across all TLDs |
| `unhuman domains register <domain>` | Register a domain (Lightning 402 payment flow) |
| `unhuman domains info <domain>` | Get domain info (expiry, nameservers, status) |
| `unhuman domains dns <domain>` | List DNS records |
| `unhuman domains dns set <domain> --records '<json>'` | Set DNS records |
| `unhuman domains nameservers <domain> <ns1> <ns2>` | Update nameservers |
| `unhuman domains renew <domain>` | Renew a domain |
| `unhuman domains recover <domain> --email <email>` | Recover a lost management token |
| `unhuman domains tokens` | List stored management tokens |

All commands support `--json` for machine-readable output.

### Autonomous Payments

Pass `--wallet` to register or renew to pay automatically using [agent-wallet](https://docs.moneydevkit.com/agent-wallet), a self-custodial Bitcoin Lightning wallet built for AI agents:

```
# Install agent-wallet (one-time setup)
npx @moneydevkit/agent-wallet init

# Register a domain — fully autonomous
unhuman domains register coolsite.dev --email me@example.com --wallet
```

This handles the entire 402 flow autonomously: get invoice → pay via agent-wallet → submit proof → receive management token. No human interaction needed.

Requires agent-wallet to be running (`npx @moneydevkit/agent-wallet init` to set up). Learn more: https://docs.moneydevkit.com/agent-wallet

### Token Storage

Management tokens are stored in `~/.unhuman/tokens.json` automatically after registration. All management commands (info, dns, nameservers, renew) load tokens from this file.

## Notes for Agents

- All prices are in USD cents. Divide by 100 for dollars.
- The `.ai` TLD has a 2-year minimum period — the price reflects 2 years.
- WHOIS privacy is always enabled by default and is not user-toggleable.
- DNS management is only available when using OpenSRS default nameservers.
- Management tokens are JWTs valid for 1 year. Store them securely.
- The `GET /api/domains` endpoint returns full endpoint documentation and is a good starting point for discovery.
- DNS PUT replaces the entire zone. Read existing records first with GET if you want to add to them.
- Lightning invoices expire in ~15 minutes. Complete payment promptly.
- If you can execute shell commands, prefer the CLI (`npx unhuman domains`) over raw HTTP — it handles the 402 payment flow, token storage, and formatting for you.