domainagent — AI Agent Guide
=========================

domainagent is a one-prompt deploy service. Register a domain, deploy your app, and configure DNS in a single API call. Payment via x402 (USDC on Base mainnet).

NO ACCOUNT NEEDED. Just a wallet address and an email address.

## Required inputs before you start
- owner: your wallet address (e.g. "0x1234...")
- email: a real email address for domain renewal notices and hosting alerts (REQUIRED — domain registration will fail without it)
- domain: the domain you want to register (e.g. "myapp.xyz")
- files: a zip file containing your app (index.html + assets, or app.js for Node apps)

## Quick Start (4 steps, no auth required)

1. Search for an available domain:
   POST /api/search { "query": "fitness app", "tlds": [".com", ".dev"] }
   → Returns available domains with prices

2. Validate inputs (FREE — call this before paying):
   POST /api/deploy/validate { "domain": "myapp.xyz", "owner": "0x...", "email": "user@example.com" }
   → Returns { valid: true, price: 13.99 } or clear error messages
   → If email is missing, you will get a 400 error telling you to collect it first
   → This step is free and catches problems before the payment is charged

3. Pay and register the domain:
   POST /api/deploy/prepare { "domain": "myapp.xyz", "owner": "0x...", "email": "user@example.com" }
   → Returns 402 Payment Required with x402 payment details
   → Pay with USDC, retry with Payment-Signature header
   → Returns { uploadToken, domain, expiresInMinutes: 30 }

4. Upload your files:
   POST /api/deploy/upload (multipart) { uploadToken, files }
   → Returns { url, domain, status: "live" }

## IMPORTANT: Email is required
Every deploy requires a real email address. This is set as the registrant contact
in the domain registrar so the domain owner receives renewal reminders and can recover
the domain. Always ask the user for their email before starting a deploy. If you are
an autonomous agent, use a contact email from your operator configuration.

## Auth (optional — only needed for managing existing deployments)
If you need to manage an existing deployment (view logs, set env vars, redeploy):
   POST /api/auth/challenge { "owner": "0x..." }
   → Sign returned message with your wallet
   POST /api/auth/verify { "owner": "0x...", "signature": "0x...", "message": "..." }
   → Returns session token for subsequent management calls
Auth is NOT required for a first-time deploy.

## Cloudflare (optional — only needed for custom DNS management)
   POST /api/connect { "cf_api_token": "..." }
Only needed if the user wants to manage DNS through their own Cloudflare account.
domainagent handles DNS automatically for all deploys — Cloudflare connect is optional.

## Redeploy an update:
   POST /api/redeploy (multipart form) { domain, owner, email, files }
   → $2 flat fee via x402

## Endpoints

### POST /api/search (free)
Search available domains.
Request:  { "query": "fitness tracker", "tlds": [".com", ".dev", ".io"] }
Response: { "results": [{ "domain": "fittrack.dev", "available": true, "price": 13.99, "currency": "USD" }] }

### POST /api/recommend (free)
AI-powered domain suggestions based on your project description.
Request:  { "description": "a fitness tracking app for runners", "budget": 20 }
Response: { "keywords": ["fitness", "tracking", "runners"], "suggestions": [...] }

### GET /api/pricing (free)
Get TLD price list and fee structure.
Response: { "tlds": { ".com": 12.99, ".dev": 13.99, ... }, "deployFee": 2.0, "redeployFee": 2.0 }

### GET /api/status/:domain (free)
Check registration and deployment status.
Response: { "domain": "fittrack.dev", "registered": true, "deployed": true, "dns": true, "ssl": true, "url": "https://fittrack.dev" }

### POST /api/deploy [x402 — domain cost + $2]
Register domain + deploy files + configure DNS in one call.
Multipart form fields:
  - domain: "fittrack.dev"
  - owner: "0x1234..." (your wallet address)
  - files: zip file containing your app (index.html + assets)
Response: { "url": "https://fittrack.dev", "domain": "...", "deployId": "...", "status": "live", "ssl": true, "dns": true }

### POST /api/redeploy [x402 — $2 flat]
Redeploy an existing site with updated files.
Multipart form fields:
  - domain: "fittrack.dev"
  - owner: "0x1234..."
  - files: updated zip file
Response: { "url": "https://fittrack.dev", "deployId": "...", "status": "live" }

### POST /api/auth/challenge (free)
Get a wallet challenge message to sign.
Request:  { "owner": "0x..." }
Response: { "message": "Sign this message...", "nonce": "..." }

### POST /api/auth/verify (free)
Verify the signed challenge and get a session token.
Request:  { "owner": "0x...", "signature": "0x...", "message": "..." }
Response: { "success": true, "token": "...", "expiresIn": "7 days" }

### POST /api/connect (free, auth required)
Connect your Cloudflare account. Deployments go to YOUR account — you own everything.
Header:   Authorization: Bearer <token>
Request:  { "cf_api_token": "your-cf-token" }
Response: { "success": true, "cf_account_id": "...", "cf_account_name": "..." }

### GET /api/domains (free, auth required)
List all domains owned by the authenticated wallet.
Header:   Authorization: Bearer <token>
Response: { "count": 2, "domains": [{ "domain": "fittrack.dev", "status": "live", ... }] }

### GET /api/health/:domain (free)
Check DNS + HTTPS + SSL + response time for a deployed domain.
Response: { "healthy": true, "dns": true, "https": true, "statusCode": 200, "responseTimeMs": 184 }

### GET /api/dns/:domain (free, auth required)
List DNS records for a domain.

### POST /api/dns/:domain (free, auth required)
Add a DNS record.
Request:  { "host": "", "type": "MX", "answer": "mail.example.com", "ttl": 300 }

### DELETE /api/dns/:domain/:recordId (free, auth required)
Delete a DNS record by ID.

### POST /api/renewal-email (free, auth required)
Set a renewal reminder email for a domain.
Request:  { "domain": "fittrack.dev", "email": "you@example.com" }
Response: { "success": true, "renewalEmail": "you@example.com" }

### GET /api/renewals-due (free)
Check domains expiring within 30 days.
Request:  GET /api/renewals-due?owner=0x...
Response: { "count": 1, "domains": [{ "domain": "fittrack.dev", "expiresIn": "12 days", ... }] }

### POST /api/renew [x402 — renewal cost + $2]
Renew a domain registration.
Request:  { "domain": "fittrack.dev", "owner": "0x..." }
Response: { "success": true, "expiresAtHuman": "2028-04-03" }

### POST /api/transfer-out (free)
Get auth code to transfer your domain to another registrar. No charge.
Request:  { "domain": "fittrack.dev", "owner": "0x..." }
Response: { "authCode": "abc123", "status": "unlocked", "instructions": [...] }

## Payment (x402)
Network:  Base mainnet (eip155:8453)
Asset:    USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
Protocol: x402 v2

Payment Flow:
1. Call /api/deploy or /api/redeploy → receive 402 with X-Payment-Required header
2. Decode payment requirements, sign USDC transfer authorization
3. Retry request with X-Payment header containing signed authorization
4. On success, receive deploy results

## Pricing
- Domain registration: $3–$90 depending on TLD (charged by Name.com)
- Deploy fee: $2 USDC per deploy
- Redeploy: $2 USDC flat per update
- Renewal: domain renewal cost + $2 USDC
- DNS + SSL: included
- Connect, search, transfer-out: FREE

## What Gets Deployed
- Static sites (HTML, CSS, JS, images)
- Single-page apps (React, Vue, Svelte builds)
- Any static content in a zip file
- Must have index.html at the root

## Pricing Notes
- Domain prices are approximate at search time; exact price confirmed at registration
- Bandwidth tracking uses real-time data from the Fly.io GraphQL API (totalDataOutGB)
- Query live usage anytime via GET /api/hosting/:domain/bandwidth
- At 80% usage you'll receive an email warning; at 100% your site pauses automatically
- Overage alerts are sent at 80% and 100% of tier allowance
- 7-day grace period before any service is paused for overages

## Tips
- Call /api/search first to find an available domain and confirm price
- Call /api/pricing to see full TLD price list and hosting tiers
- Your site will be live at https://yourdomain.com within ~1 minute of payment
- SSL is automatic — no config needed
- Redeploy as many times as you need at $0.50 each
- App tiers (app_sm/md/lg) run 24/7 with no cold starts
- Static tiers sleep after ~5 min idle (fine for sites, not APIs)