# AgentDomains API

> Domain registrar built for autonomous AI agents. API-first. No dashboard required.
> Payment options: Stripe invoice, direct crypto payment, or crypto-purchased credit balance.

## Authentication
SSH Ed25519 keypair challenge-response. Generate a keypair, sign a challenge, get an API key.

## Quick Start
1. POST /api/auth/challenge with { "publicKey": "<your ed25519 public key>" }
2. Sign the challenge via stdin: echo -n "<challenge>" | ssh-keygen -Y sign -f ~/.ssh/key -n agentdomains -
3. POST /api/auth/verify with { "challengeId": "<from step 1>", "signature": "<from step 2>" }
4. Use the returned apiKey as: Authorization: Bearer <apiKey>

## Registrant Info (Required)

All registrations must include registrant info in the request body.

⚠️ CRITICAL — ICANN Verification & Registrant Accuracy:
- ALL registrant information MUST be real and accurate. This is a LEGAL REQUIREMENT.
- After registration, a verification email is sent to the registrant email address.
- If the email is not verified within 14 DAYS, the domain WILL BE SUSPENDED.
- No refunds can be offered for suspended domains.
- DO NOT use fake names, placeholder emails, or invented addresses.
- The email MUST belong to your human handler — they need to click the verification link.
- Ask your human for their real info before registering. Don't guess or make it up.

## Payment Options

1) Human-in-the-loop (default): Stripe invoice payment page. paymentMethod: "invoice".
2) Credit balance: purchase credits with crypto, then use paymentMethod: "credits" on domain registration for instant, no-human-needed purchases. Exchange fees apply at the NOWPayments level; use stablecoins (USDT, USDC) for minimal conversion overhead.
3) Direct crypto payment: paymentMethod: "crypto" creates a NOWPayments hosted checkout page. Send the URL to your human — they pay with crypto, domain registers automatically. Optional: payCurrency to pre-select a crypto (e.g. "btc", "usdttrc20").

Every domain action can create a human-friendly payment page when needed.

### Register a Domain

POST /api/domains/register
{
  "domain": "example.com",
  "registrant": { "firstName": "Jane", "lastName": "Smith", "email": "jane@example.com", "phone": "+1.4155551234", "address": { "street": "123 Main St", "city": "San Francisco", "state": "CA", "postalCode": "94102", "country": "US" } }
}

Returns:
{
  "paymentUrl": "https://agentdomains.dev/pay/clxyz123",
  "invoice": { "id": "clxyz123", "amount": 1318, ... }
}

Send the paymentUrl to your human. They open it, see what you want to register and the
price, enter their card, and pay. The domain registers automatically after payment.

For multiple domains at once:
POST /api/domains/register/batch
{
  "registrant": { "firstName": "Jane", "lastName": "Smith", "email": "jane@example.com", "phone": "+1.4155551234", "address": { "street": "123 Main St", "city": "San Francisco", "state": "CA", "postalCode": "94102", "country": "US" } },
  "domains": [{ "domain": "one.dev" }, { "domain": "two.dev" }]
}

Returns a single paymentUrl for all domains combined.

### Renew a Domain

POST /api/domains/{domain}/renew
{ "period": 1 }

Returns a paymentUrl. Send it to your human to pay for the renewal.

## What Your Human Sees

When a human opens the payment URL, they see:
- What you (the agent) want: "Your agent wants to register coolbot.dev"
- The exact price: "$13.18 for 1 year"
- Renewal price hint (for registrations)
- Alternative TLD options (if provided)
- Stripe card payment form

## Contact Management

GET /api/domains/{domain}/contacts — returns all four WHOIS contact types.

PUT /api/domains/{domain}/contacts — update one or more contact types.
{
  "registrant": { "firstName": "Jane", "lastName": "Smith", "email": "jane@example.com", "phone": "+1.4155551234", "address": { "street": "123 Main St", "city": "SF", "state": "CA", "postalCode": "94102", "country": "US" } }
}

You only need to provide the contact types you want to change. The others are kept as-is.

⚠️ ICANN Email Verification:
If you change the registrant email address, a new verification email is sent to the NEW address.
That email MUST be verified within 14 days or the domain WILL BE SUSPENDED.
Make sure the new email is real and accessible by your human handler.

## DNS Record Example

POST /api/domains/{domain}/dns
{ "type": "A", "name": "@", "content": "1.2.3.4" }

Supported types: A, AAAA, CNAME, MX, TXT, SRV, CAA

## Email Forwarding

GET /api/domains/{domain}/email-forwarding — returns current forwarding rules.

PUT /api/domains/{domain}/email-forwarding — replace all forwarding rules.
{
  "rules": [
    { "alias": "hello", "forwardTo": "jane@gmail.com" },
    { "alias": "support", "forwardTo": "team@company.com" }
  ]
}

The "alias" field is the mailbox prefix (without @domain). The "forwardTo" field is the destination email.

## Domain Expiration

Auto-renew is disabled. Domains expire unless explicitly renewed.

All domain management endpoints (DNS, nameservers, contacts, email-forwarding) include:
- expiresAt: ISO 8601 expiry date
- expirationWarning (if within 30 days): { message, daysRemaining, renewEndpoint }

Warning tiers:
- <=7 days: "Urgent" — renew immediately
- <=14 days: "Expiring soon" — renew to avoid losing it
- <=30 days: "Approaching" — consider renewing

GET /api/account includes an expiringDomains array — domains expiring within 30 days.
This is the best single place to check for upcoming expirations.

To renew: POST /api/domains/{domain}/renew — returns a payment URL.

## Pagination

List endpoints (GET /api/domains, GET /api/invoices) support cursor-based pagination.
Query parameters: ?cursor=<lastItemId>&limit=<number>
- cursor: ID of the last item from the previous page (omit for the first page)
- limit: number of items per page (default 20, max 100)
Response includes: { items: [...], nextCursor: "..." }
When nextCursor is null, there are no more pages.

## Support Tokens

If your human needs to contact support on your behalf, generate a support token first:
GET /api/account/support-token — returns a token valid for 24 hours.
Give the token to your human. They include it in their email to support@agentdomains.dev.
Support uses the token to verify the human is authorized to act on your behalf.

## Account Deletion

DELETE /api/account — request account deletion.
This soft-deletes your agent account and anonymizes PII. Domains remain registered until expiry.

## Endpoints

### Authentication
- POST /api/auth/challenge — Request a signing challenge (no auth)
- POST /api/auth/verify — Verify signature and get API key (no auth)

### Account
- GET /api/account — Account info
- GET /api/account/support-token — Generate a 24-hour support token for your human
- DELETE /api/account — Delete account (soft-delete + PII anonymization)

### Domain Registration
- GET /api/domains/check?domain=example.dev — Check availability + pricing (no auth)
- POST /api/domains/check/bulk — Bulk domain availability check, up to 50 domains (no auth)
  Tip: If checking more than one domain, always use /check/bulk instead of calling /check in a loop.
  POST /api/domains/check/bulk { "domains": ["one.dev", "two.dev", "three.dev"] }
- GET /api/domains/tlds — List supported TLDs with pricing (no auth)
- GET /api/domains/pricing — All-TLD pricing data (no auth)
- GET /api/domains/pricing/{domain} — Get per-domain pricing (no auth)
- POST /api/domains/register — Register a domain (returns payment URL)
- POST /api/domains/register/batch — Register multiple domains in one request
- GET /api/domains — List your domains

### Domain Management
- POST /api/domains/{domain}/renew — Renew a domain (returns payment URL)
- GET /api/domains/{domain}/contacts — Get current WHOIS contacts (Registrant, Admin, Tech, AuxBilling)
- PUT /api/domains/{domain}/contacts — Update WHOIS contacts (provide only the types you want to change)
- GET /api/domains/{domain}/nameservers — Get current nameservers
- PUT /api/domains/{domain}/nameservers — Update nameservers
- GET /api/domains/{domain}/email-forwarding — Get email forwarding rules
- PUT /api/domains/{domain}/email-forwarding — Set email forwarding rules
- GET /api/domains/{domain}/dns — Get DNS records
- POST /api/domains/{domain}/dns — Create DNS record
- DELETE /api/domains/{domain}/dns — Delete DNS record

### Payment Management
- GET /api/invoices — List invoices
- GET /api/invoices/{id} — Invoice details
- POST /api/invoices/{id}/pay — Get new payment URL for a pending invoice

### Crypto Payments
- POST /api/credits/purchase/crypto — Purchase credits with cryptocurrency
- GET /api/credits/purchase/crypto/{id} — Check crypto payment status
- GET /api/crypto/currencies — List available cryptocurrencies
- GET /api/crypto/estimate — Get crypto price estimate

Credits are added to your account when payment completes. Use paymentMethod: "credits"
on POST /api/domains/register to spend credits directly without human payment.
Note: Crypto-to-USD conversion is handled by NOWPayments; their exchange rate includes
processing fees. Use stablecoins (USDT, USDC) for minimal conversion overhead.

You can also use paymentMethod: "crypto" on register endpoints to pay for domains directly
with crypto (without pre-purchasing credits). This creates a NOWPayments checkout page that
your human opens to pay. The domain registers automatically after payment.

### Discovery
- GET /api — Full API documentation (JSON)
- GET /api/openapi.json — OpenAPI 3.1 spec
- GET /.well-known/agent.json — Agent discovery
- GET /api/health — Health check
- GET /api/version — API version info

## Registrant Info

Registrant info is required on every registration request (ICANN rules).

- Single registration: include a registrant object in POST /api/domains/register.
- Batch registration: include a top-level registrant; per-domain overrides are allowed.

## Pricing
All prices in cents (USD). Wholesale cost + flat $3.00 markup.
Multi-year registrations: year 1 full markup, years 2+ at $1.50/yr (50% off).

## Recommendation
Register for 2+ years. Domain prices trend upward over time, so multi-year registration
locks in today’s price and reduces renewal risk.
Pass { "period": 2 } on register or renew endpoints.

## Payment Flow
Every purchase returns a paymentUrl pointing to a human-friendly payment page.
Send this URL to your human via whatever channel you use (chat, email, etc).
The payment page shows:
- What the agent wants to do (register/renew)
- The domain name
- The exact price
- A Stripe card payment form

After payment, the domain is automatically registered/renewed. No further action needed.

## Payment Responses
When a payment URL is returned, the response includes a nextSteps object with guidance:
- action: what needs to happen (e.g. "human_payment_required")
- paymentUrl: the payment page link
- amount: formatted price
- onSuccess / onFailure: what happens after payment
- tip: how to forward the URL to the human

## Refund Protection
If a domain is registered by someone else between invoice creation and payment completion,
a full refund is automatically issued. The invoice status will show "REFUNDED" with details.

## Credit Refund Rules
- Credits purchased with crypto are non-refundable to the original wallet.
- If a domain registration paid with credits fails, credits are returned to your balance automatically.
- If a domain registration paid directly with crypto (paymentMethod: "crypto") fails, the refund is issued as credits to your account balance (not back to crypto).
- Partial crypto payments (insufficient amount sent) require contacting support.
- Credits do not expire but are forfeited on account deletion.
- For Stripe-paid invoices, refunds go back to the original payment method.

## Sandbox
A sandbox environment is available at https://sandbox.agentdomains.com for testing.
It mirrors the production API with test registrar and payment backends.
Use it to experiment with auth, domain registration, DNS, and payment flows without real charges.

## Rate Limits
Authenticated: 100 req/min per API key. Unauthenticated (domain check): 100 req/min per IP.
Exceeding the limit returns 429 Too Many Requests.
Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After (on 429).

## Idempotency
POST/PUT/DELETE endpoints accept an Idempotency-Key header.
Duplicate requests with the same key return the cached response for 24 hours.
Useful for safely retrying failed requests without creating duplicate invoices or registrations.

## Key Features
- SSH Ed25519 auth (no email/OAuth)
- Payment options: Stripe invoice, crypto credits, or direct crypto payment (exchange fees apply at NOWPayments level)
- Per-purchase payment pages (no pre-funding needed)
- Idempotency keys (Idempotency-Key header)
- Rate limiting (100 req/min, X-RateLimit-* headers)
- Automatic refunds on domain race conditions