# AI Site Agent

> Register a domain, deploy a site, and go live — one API call, paid with crypto via x402.

## Agent Role

**You are a conversational text agent.** Your job is to talk to the user, call this API, and report results back in plain text.

**You must NOT:**
- Generate HTML, CSS, JavaScript, or any web content yourself
- Build a site builder, UI, or any front-end application
- Attempt to write or deploy files directly
- Proceed to payment without explicit user confirmation

**The `prompt` field in `/provision` is a natural-language description you pass to the server.** The server's AI generates the actual site. You write a description; the API does the building.

## Conversational Flow (follow this order)

1. **Collect intent** — ask the user what kind of website they want. Get enough to write a good description: business name, what they sell, target audience, tone, key CTA, any style preferences.
2. **Plan** — call `POST /agent/plan` with the user's message. Present the top 3–5 domain candidates with prices as a text list. Ask the user to pick one.
3. **Confirm** — show the selected domain and total cost (`quotes.withGenerate.totalUsd`). Ask "Proceed?" before any payment.
4. **Provision** — only after explicit user confirmation, call `POST /provision`. Handle 402 → sign → retry.
5. **Poll** — call `GET /jobs/<id>` every few seconds until `status === "completed"` or `"failed"`. Report progress as plain text.
6. **Done** — report the live URL, domain, and any next steps in plain text.

## Quick Start for Agents

1. **Discover** — `GET http://77.42.88.70/capabilities` for fee schedule and endpoint list.
2. **Plan** — `POST http://77.42.88.70/agent/plan` with `{ "message": "user request" }` to get ranked domain candidates + provision payload in one call.
3. **Provision** — `POST http://77.42.88.70/provision` with chosen options; handle 402 → sign → retry with payment headers.
4. **Poll** — `GET http://77.42.88.70/jobs/<id>` until `status === "completed"`.

All requests use `Content-Type: application/json`. On 429 (rate limited), wait 60 seconds and retry.

## Base URL

http://77.42.88.70

**Test mode:** This instance uses `skipDomainPurchase=true` with domain `testdomain4000.site`. Registrar purchase and nameserver updates are skipped.

## Authentication

This API uses the [x402 payment protocol](https://docs.x402.org). Paid endpoints return `402 Payment Required` with a price quote and payment instructions on first request. Retry with x402 payment headers after signing to proceed. Payments are ERC-20 stablecoin transfers on network `eip155:84532`.

## Fee Schedule

- **Domain registration commission**: 15% of registrar cost (min $2.00, max $25.00)
- **Static file deployment**: +$1.50 flat fee (when providing `files`)
- **AI site generation**: +$5.00 flat fee (when providing `prompt`)
- Domain registrar costs are fetched live from Namecheap. Call `POST /domains/check` to get an exact quote before paying.

## Endpoints

### GET /health

Returns `{ "ok": true }` if the service is running. No auth required.

### GET /capabilities

Returns full service metadata including fee schedule, endpoint descriptions, and auth info. No auth required.

### GET /llms.txt

This file. No auth required.

### GET /docs

Interactive Swagger UI. No auth required.

### GET /openapi.json

OpenAPI 3.0.3 specification. No auth required.

### POST /agent/plan (free, rate-limited)

Agent helper endpoint for **Step A / Step B**:

- parses user intent from natural language
- generates candidate domains
- fetches availability + quote previews
- returns a ranked shortlist
- returns a ready-to-send `/provision` payload preview

Rate-limited to 10 requests/minute per IP. On 429, wait ~60s and retry.

**Request body:**

```json
{ "message": "Create a website for eco-friendly dog food", "topK": 5 }
```

### POST /domains/check (free, rate-limited)

Check if a domain is available and get price quotes for all provisioning modes. Rate-limited to 10 requests/minute per IP. On 429, wait ~60s and retry.

**Request body:**

```json
{ "domain": "example.com" }
```

**Response** includes availability, registration period, and three quotes (domain only, with files, with AI generation). Use the `totalUsd` field from the relevant quote to know what the `/provision` call will cost.

### POST /provision (paid via x402)

Register a domain, configure Cloudflare (zone, Pages project, DNS, nameservers), and optionally deploy content. Returns a job ID for async polling.

**Request body:**

```json
{
  "domain": "example.com",
  "projectName": "my-project",
  "files": { "index.html": "<html>...</html>" },
  "prompt": "Build a landing page for an eco-friendly dog food brand",
  "branch": "main",
  "includeWww": true
}
```

- `domain` is required. Everything else is optional.
- Provide `files` (map of filepath → content) OR `prompt` (AI generation), not both.
- **`prompt` is a plain-text description** — the server's AI generates the site from it. Do not put HTML or code here. Write a natural-language brief (business, audience, tone, CTA, sections needed).
- If neither `files` nor `prompt` is given, the domain is registered with an empty Pages project.

**Flow:**
1. First call returns `402` with a price quote and x402 payment instructions.
2. Sign and retry with payment headers.
3. Returns `202` with `{ "jobId": "...", "poll": "/jobs/<id>" }`.
4. Poll `GET /jobs/<id>` until status is `completed` or `failed`.

### GET /jobs/:id (free)

Poll the status of a provisioning job. Returns the job object with step-by-step progress, result (when completed), or error (when failed).

## Typical Agent Workflow

This is a **conversational** flow. Each step involves talking to the user.

1. **Ask** — collect the user's website idea via text conversation (business, audience, tone, CTA, style). No UI needed.
2. **Plan** — `POST /agent/plan` with the user's message. Present the returned domain candidates as a plain-text list with prices. Ask the user to pick one.
3. **Confirm** — tell the user the selected domain and total cost. Ask "Ready to proceed?" before spending anything.
4. **Provision** — only after "yes": `POST /provision` with `domain`, `projectName`, and a `prompt` field containing a **text description** of the site (not HTML — the server generates the site from your description). Handle the x402 payment flow.
5. **Poll** — `GET /jobs/<id>` until `status === "completed"` or `"failed"`. Narrate progress to the user in plain text.
6. **Done** — report the live URL, domain, and next steps in a plain-text message.

## Schemas

### AgentPlanRequest

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1
    },
    "topK": {
      "type": "integer",
      "minimum": 1,
      "maximum": 15,
      "default": 5
    }
  },
  "required": [
    "message"
  ],
  "additionalProperties": false
}
```

### AgentPlanResponse

```json
{
  "type": "object",
  "properties": {
    "intent": {
      "type": "object",
      "properties": {
        "rawMessage": {
          "type": "string"
        },
        "businessIdea": {
          "type": "string"
        },
        "keywords": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "rawMessage",
        "businessIdea",
        "keywords"
      ],
      "additionalProperties": false
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string"
          },
          "available": {
            "type": "boolean"
          },
          "score": {
            "type": "number"
          },
          "rationale": {
            "type": "string"
          },
          "quotes": {
            "type": "object",
            "properties": {
              "domainOnly": {
                "type": "object",
                "properties": {
                  "registrarCostUsd": {
                    "type": "number"
                  },
                  "commissionRate": {
                    "type": "number"
                  },
                  "commissionUsd": {
                    "type": "number"
                  },
                  "deployFeeUsd": {
                    "type": "number"
                  },
                  "generateFeeUsd": {
                    "type": "number"
                  },
                  "totalUsd": {
                    "type": "number"
                  }
                },
                "required": [
                  "registrarCostUsd",
                  "commissionRate",
                  "commissionUsd",
                  "deployFeeUsd",
                  "generateFeeUsd",
                  "totalUsd"
                ],
                "additionalProperties": false
              },
              "withGenerate": {
                "$ref": "#/properties/candidates/items/properties/quotes/properties/domainOnly"
              }
            },
            "required": [
              "domainOnly",
              "withGenerate"
            ],
            "additionalProperties": false
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "domain",
          "available",
          "score",
          "rationale"
        ],
        "additionalProperties": false
      }
    },
    "selectedDomain": {
      "type": "string",
      "nullable": true
    },
    "testMode": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "domain": {
          "type": "string"
        }
      },
      "required": [
        "enabled"
      ],
      "additionalProperties": false
    },
    "provisionPayloadPreview": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string"
        },
        "prompt": {
          "type": "string"
        },
        "projectName": {
          "type": "string"
        },
        "includeWww": {
          "type": "boolean"
        },
        "skipDomainPurchase": {
          "type": "boolean"
        }
      },
      "required": [
        "domain",
        "prompt",
        "projectName",
        "includeWww",
        "skipDomainPurchase"
      ],
      "additionalProperties": false,
      "nullable": true
    }
  },
  "required": [
    "intent",
    "candidates",
    "selectedDomain",
    "testMode",
    "provisionPayloadPreview"
  ],
  "additionalProperties": false
}
```

### DomainCheckRequest

```json
{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "domain"
  ],
  "additionalProperties": false
}
```

### DomainCheckResponse

```json
{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string"
    },
    "available": {
      "type": "boolean"
    },
    "sandbox": {
      "type": "boolean"
    },
    "registrationYears": {
      "type": "integer"
    },
    "quotes": {
      "type": "object",
      "properties": {
        "domainOnly": {
          "type": "object",
          "properties": {
            "registrarCostUsd": {
              "type": "number"
            },
            "commissionRate": {
              "type": "number"
            },
            "commissionUsd": {
              "type": "number"
            },
            "deployFeeUsd": {
              "type": "number"
            },
            "generateFeeUsd": {
              "type": "number"
            },
            "totalUsd": {
              "type": "number"
            }
          },
          "required": [
            "registrarCostUsd",
            "commissionRate",
            "commissionUsd",
            "deployFeeUsd",
            "generateFeeUsd",
            "totalUsd"
          ],
          "additionalProperties": false
        },
        "withFiles": {
          "$ref": "#/properties/quotes/properties/domainOnly"
        },
        "withGenerate": {
          "$ref": "#/properties/quotes/properties/domainOnly"
        }
      },
      "required": [
        "domainOnly",
        "withFiles",
        "withGenerate"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "domain",
    "available",
    "sandbox",
    "registrationYears",
    "quotes"
  ],
  "additionalProperties": false
}
```

### ProvisionRequest

```json
{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "minLength": 1
    },
    "projectName": {
      "type": "string"
    },
    "files": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "prompt": {
      "type": "string"
    },
    "branch": {
      "type": "string",
      "default": "main"
    },
    "includeWww": {
      "type": "boolean",
      "default": true
    },
    "skipDomainPurchase": {
      "type": "boolean"
    }
  },
  "required": [
    "domain"
  ],
  "additionalProperties": false
}
```

### ProvisionAcceptedResponse

```json
{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "processing"
      ]
    },
    "poll": {
      "type": "string"
    }
  },
  "required": [
    "jobId",
    "status",
    "poll"
  ],
  "additionalProperties": false
}
```

### PaymentRequiredResponse

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "payment_required"
      ]
    },
    "hint": {
      "type": "string"
    },
    "quote": {
      "type": "object",
      "properties": {
        "registrarCostUsd": {
          "type": "number"
        },
        "commissionRate": {
          "type": "number"
        },
        "commissionUsd": {
          "type": "number"
        },
        "deployFeeUsd": {
          "type": "number"
        },
        "generateFeeUsd": {
          "type": "number"
        },
        "totalUsd": {
          "type": "number"
        },
        "domain": {
          "type": "string"
        },
        "existingDomainMode": {
          "type": "boolean"
        }
      },
      "required": [
        "registrarCostUsd",
        "commissionRate",
        "commissionUsd",
        "deployFeeUsd",
        "generateFeeUsd",
        "totalUsd",
        "domain",
        "existingDomainMode"
      ],
      "additionalProperties": false
    },
    "domain": {
      "type": "string"
    },
    "existingDomainMode": {
      "type": "boolean"
    }
  },
  "required": [
    "error",
    "hint"
  ],
  "additionalProperties": false
}
```

### ProvisionQuote

```json
{
  "type": "object",
  "properties": {
    "registrarCostUsd": {
      "type": "number"
    },
    "commissionRate": {
      "type": "number"
    },
    "commissionUsd": {
      "type": "number"
    },
    "deployFeeUsd": {
      "type": "number"
    },
    "generateFeeUsd": {
      "type": "number"
    },
    "totalUsd": {
      "type": "number"
    }
  },
  "required": [
    "registrarCostUsd",
    "commissionRate",
    "commissionUsd",
    "deployFeeUsd",
    "generateFeeUsd",
    "totalUsd"
  ],
  "additionalProperties": false
}
```

### Job

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "provision"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "processing",
        "completed",
        "failed"
      ]
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "done",
              "failed",
              "skipped"
            ]
          },
          "detail": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "name",
          "status",
          "at"
        ],
        "additionalProperties": false
      }
    },
    "input": {
      "type": "object",
      "additionalProperties": {}
    },
    "result": {
      "type": "object",
      "additionalProperties": {}
    },
    "error": {
      "type": "string"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "type",
    "status",
    "steps",
    "input",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false
}
```

### ErrorResponse

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

## Links

- [OpenAPI spec](http://77.42.88.70/openapi.json)
- [Swagger UI](http://77.42.88.70/docs)
- [x402 protocol docs](https://docs.x402.org)