# Headless Domains - Full LLM Context

This file contains the expanded, full context for Headless Domains.

## 1. System Overview
Headless Domains acts as a Combined Monolith (Registry + Registrar) for the Headless Ecosystem. We specialize in providing verifiable, machine-readable namespaces (like `.agent`, `.chatbot`) for autonomous AI agents. 

Our DNS backend is powered by SkyInclude (Handshake). We provide a custom "Wholesale Registry API" for developers to build their own marketplaces.

## 2. API Endpoints
All API endpoints are located under `https://headlessdomains.com/api/v1/`.

### 2.1 Search
`GET /api/v1/domains/search?q={domain}`
Returns JSON indicating if a domain is available.

### 2.2 Registration
`POST /api/v1/domains/register`
Requires a domain label/namespace, `years`, acceptance of the terms, and either an authenticated Gem payment or an MPP payment credential.

### 2.3 Quote
`POST /api/v1/domains/quote`
Returns an authenticated, non-binding price and payment-rail quote without creating an order or reserving a domain. Agents should use this before initiating a paid registration.

### 2.4 Whois / Lookup
`GET /api/v1/lookup/{domain}`
Returns the domain's public profile, agent manifest, supported capabilities (SKILL.md), and commerce capabilities (`identity.commerce`).

### 2.5 Canonical Resolver
`GET /api/v1/resolve/{domain}`
Returns the versioned canonical representation for `.agent`, `.chatbot`, `.boss`, `.factory`, `.protocol`, and `.bpo`: lifecycle state, public identity, capabilities, validated actions, manifest/SKILL.md resources, service discovery, and separated trust observations. Use this endpoint before invoking an advertised action.

Action cards conform to `https://headlessdomains.com/schemas/action-card-v1.schema.json`. Each card declares the operator, execution provider and provenance, invocation/authentication metadata, approval and data scopes, risk, verification evidence, payment/refund authority, receipt authority, and revocation state. Resolution is discovery only: HeadlessDomains does not proxy arbitrary provider URLs, and caller authorization remains the execution provider's responsibility.

For an active supported domain with Agent Inbox enabled, `contact.send_message` invokes `POST https://inbox.headlessdomains.com/<domain>/messages` with required JSON `body`. The human page remains `https://inbox.headlessdomains.com/<domain>`. A new or de-duplicated delivery acknowledgement exposes its message ID at `data.id`; that ID can be matched through the explicitly authorized owner API. Expired, suspended/flagged, unsupported, and disabled domains report effective Inbox availability as false so the data plane rejects direct submission too. Ownership and enabled configuration do not prove endpoint reachability, so resolver health remains `not_probed` without an independent probe. A general PowerLobster/GFAVIP identity is not automatically authorized to manage or read a domain Inbox.

### 2.6 Marketplace
We encourage third-party marketplaces. See our [Marketplace API Docs](https://docs.headlessdomains.com/guides/secondary-market/) for details.

## 3. Integrations & Identity Management
- **Identity Provider (Decentralized):** We act as an identity provider for autonomous agent authentication and authorization management. We intentionally bypass legacy Web2 protocols (OAuth 2.0, OpenID Connect) in favor of verifiable DNS TXT records (DIDs, Matrix IDs).
- **Authentication & Permission Scoping:** API access is delegated via API Keys (`X-API-Key`) with explicit permission scoping (e.g., `domain:read`, `domain:write`, `profile:sync`, `reseller:manage`).
- **Streaming & Event-Based APIs:** Real-time identity synchronization is supported via standard webhooks (`POST /api/v1/integrations/*/sync`) and our streaming Server-Sent Events (SSE) API endpoint (`https://mcp.headlessdomains.com/sse`) for MCP clients.
- **PowerLobster:** We sync domain bio data directly. Updates to a domain bio automatically push to the agent's `SKILL.md` and `_powerlobster_manifest`.
- **BMOS (BuildMyOnlineStore):** We support 1-to-1 agentic commerce integrations. BMOS syncs via webhook and updates the `commerce_catalog` field in the domain bio.

## 4. Machine Payments Protocol (MPP) & GFA Gems
Headless Domains operates natively on MPP to allow agents to independently register domains without human intervention.
- **Settlement networks:** MPP supports pathUSD on Tempo and native USDC on Base mainnet. Base USDC sessions, EIP-3009 settlement, receipts, and signed webhooks are delegated to `machine.checkout.best`; HeadlessDomains retains retail pricing and provisioning. Stable create-session idempotency and explicit Partners-backed Base network persistence prevent fallback to a second facilitator. Base Sepolia is reserved for testing and has no customer monetary value.
- **The MPP 402 Flow:** When an agent calls a paid endpoint (like `POST /api/v1/domains/register`) without a valid payment, the server returns `402 Payment Required` plus a `WWW-Authenticate: Payment ...` challenge and structured payment details.
- **Execution:** The agent validates the challenge network, token contract, recipient, amount, and expiry; signs or fulfills it through the selected MPP provider; then replays the identical request with the resulting `Authorization: Payment ...` credential. Successful responses include the payment reference, order, and domain identifiers so a lost response can be retried safely.
- **GFA Gems Subsidized Pricing:** Agents that authenticate with an `X-API-Key` and pass `"payment_method": "gems"` in the payload bypass the pathUSD MPP challenge. The cost is automatically deducted from their GFAVIP wallet balance at a heavily subsidized agent rate (e.g., 1 Gem vs 50).

## 5. Name Restrictions
- 1 to 63 characters long.
- Only alphanumeric characters (a-z, 0-9) and hyphens (-).
- Cannot start or end with a hyphen.
- "Fake emojis" / Zero Width Joiners (ZWJ) are strictly discouraged and display warnings.

## 6. Pricing
See [pricing.md](/pricing.md) for full details on Gems vs MPP and tiered pricing.

## 7. SDKs
- **Python SDK:** Available on GitHub at `https://github.com/shadstoneofficial/headlessdomains-python-sdk`