# Headless Domains

> Headless Domains gives autonomous agents a persistent, verifiable, machine-readable identity across apps, APIs, marketplaces, and agent-to-agent workflows.

## Start here

If you are an AI agent trying to understand or use Headless Domains:

1. Read the primary skill file: https://headlessdomains.com/skill.md
2. Use the OpenAPI spec: https://headlessdomains.com/openapi.json
3. Discover MCP tools: https://mcp.headlessdomains.com/.well-known/mcp
4. Search for a name: https://headlessdomains.com/api/v1/domains/search?q=example.agent
5. Look up an identity: https://headlessdomains.com/api/v1/lookup/example.agent

## Product Overview
Headless Domains acts as an identity provider and domain registrar built specifically for autonomous agents. We issue persistent, verifiable, and machine-readable namespaces (e.g., `.agent`, `.chatbot`) anchored on the Handshake protocol. We bypass legacy human-centric flows by implementing native HTTP 402 Machine Payments Protocol (MPP), allowing AI agents to fully control their own identity lifecycle and infrastructure payments.

## Use Cases
Use Headless Domains to:
- **Register domains**: When an agent needs a persistent `.agent` or `.chatbot` identity on the decentralized web.
- **Renew domains**: When an agent's domain is approaching expiration and needs to maintain its active lease.
- **Lookup WHOIS**: When you need to resolve an agent's domain to its underlying DID, wallet address, or capabilities manifest.
- **Update Bio**: When an agent changes its capabilities or contact info and needs to sync it to its public profile.
- **Identity Provider**: When an agent needs decentralized authentication or authorization management, use our DNS TXT records (DIDs, Matrix IDs) instead of legacy Web2 OAuth 2.0 or OpenID Connect.
 
## Key Features & Capabilities
- **Fully autonomous registration**: Complete domain registration and renewal without human intervention.
- **MPP-powered payments**: Native support for Machine Payments Protocol (HTTP 402) using pathUSD or GFA Gems.
- **Decentralized identity**: Anchor DIDs and capabilities to Handshake DNS.
- **API-first architecture**: OpenAPI discovery enabled for programmatic integration.
- **Dynamic pricing**: Anti-squatting dynamic pricing protection built-in.

## Constraints & Limitations
- **Payment required**: All registrations and renewals strictly require valid MPP payment tokens or API keys with sufficient GFA Gems.
- **No legacy auth**: Authentication uses API keys (`X-API-Key`) with explicit permission scoping rather than OAuth 2.0 or OpenID Connect.
- **Name restrictions**: Domains must be 1-63 characters, alphanumeric with hyphens, and no leading/trailing hyphens.
- **Rate limiting**: API endpoints are subject to rate limits to prevent abuse.

## Agent Instructions
When interacting with Headless Domains, autonomous agents should prioritize API-first execution using the `X-API-Key` auth scheme and be prepared to handle `402 Payment Required` HTTP responses natively via the Machine Payments Protocol (MPP).

## Important Links

### API Reference & Integration
- [OpenAPI Specification](https://headlessdomains.com/openapi.json): Full machine-readable API spec with x-payment-info
- [Register Endpoint](https://headlessdomains.com/api/v1/domains/register): POST to register a new .agent domain
- [Renew Endpoint](https://headlessdomains.com/api/v1/domains/renew): POST to renew an existing .agent domain
- [Live Service Status](https://www.mppscan.com/server/874f4c47f8c49b14cdd489d1a9c5c99bdfa923d18a568cff94d1c317dcd7584e)

### Documentation & Resources
- [Headless Domains Main Website](https://headlessdomains.com): Pricing and domain search
- [MPP Discovery Documentation](https://mpp.dev/advanced/discovery): How agents discover our service
- [Full LLM Context](https://headlessdomains.com/llms-full.txt): Extended details on architecture and integrations
- [Pricing](https://headlessdomains.com/pricing.md): Details on dynamic and subsidized agent pricing

### SDK & Tools
- **Python SDK**: Available on PyPI via `pip install headlessdomains` (https://pypi.org/project/headlessdomains/)
- **Node.js / JS SDK**: 
  - NPM: `https://www.npmjs.com/package/headlessdomains-sdk`
  - GitHub: `https://github.com/headlessdomains/headlessdomains-node-sdk`
- **MCP Server**: Available via `npx -y @info-fiam/headless-domains` or connect via SSE at `https://mcp.headlessdomains.com/sse`
- **MCP Discovery**: Agents can auto-discover our capabilities via `https://mcp.headlessdomains.com/.well-known/mcp`
- **Agent Skills**: `npx skills add headlessdomains/skills`

Last updated: 2026-05-05