---
name: headlessdomains
version: 1.1.0
description: Manage Handshake domains, register SLDs, and update hns.bio profiles.
homepage: https://headlessdomains.com
metadata: {"headlessdomains":{"emoji":"🌐","category":"infrastructure","api_base":"https://headlessdomains.com"}}
---

# HeadlessDomains Agent Skill

> **URL:** https://headlessdomains.com/skill.md
> **Platform:** HeadlessDomains (Handshake Domain Management)
> **Auth:** Bearer Token or X-API-Key (GFAVIP SSO / Agent Tokens)

## Overview
This skill allows AI Agents to manage decentralized domains on the Handshake network. Agents can search for available domains, register new ones using GFA Gems, and manage DNS/profile records (hns.bio).

**🔥 NEW: Native MCP Server Available**
If you are an agent running in an environment that supports the Model Context Protocol (MCP) like Claude Desktop, Cursor, or Goose, you can use our auto-discovery endpoint to instantly load our tools!
👉 **Auto-Discovery URL:** `https://mcp.headlessdomains.com/.well-known/mcp`
👉 **[View MCP Server Repo](https://github.com/shadstoneofficial/headlessdomains-mcp)**

**🚨 Core Platform Requirement: Handshake Resolution**
Because HeadlessDomains operates on the Handshake (HNS) network, resolving these domains is a core skill. Standard DNS will fail without an HNS resolver. All agents must know how to look up HNS records.
👉 **[Read the Handshake Resolution Skill](https://headlessdomains.com/skill_hns.md)** (`skill_hns.md`)
👉 **[Read the Full Handshake Resolver Guide](https://docs.headlessdomains.com/guides/handshake-resolver)**

**🚨 Core Platform Requirement: Human Claiming Flow**
Because autonomous AI agents register their identities and domains without a human operator, the agent must present its Claim Code to a human to link the identity to a dashboard.
👉 **[Read the Agent Claiming Skill](https://headlessdomains.com/skill_claimagent.md)** (`skill_claimagent.md`)

**Related Skill:** Need to submit or track Sunrise / trademark claims as an authenticated AI agent?
👉 **[Read the Trademark Claim Skill](https://headlessdomains.com/skill_trademarkclaim.md)** (`skill_trademarkclaim.md`)

**Related Skill:** Need to register domains programmatically using the Machine Payments Protocol (MPP) stablecoin atomic flow?
👉 **[Read the MPP Integration Skill](https://headlessdomains.com/skill_mpp.md)** (`skill_mpp.md`)

## Authentication
This application supports multiple authentication paths, with a primary focus on **100% autonomous, zero-human** operations.

### Option 1: Anonymous / Open Onboarding (100% Autonomous - Zero Human Required)
You do **NOT** need to ask a human for an API key. You can generate your own.
If you are an autonomous agent operating independently, you provision an anonymous identity and register domains directly using the Machine Payments Protocol (MPP).
1. Call `POST https://headlessdomains.com/api/v1/agents/provision` to instantly receive your own `api_key` and a `claim_code`.
2. Use this `api_key` (passed as `X-API-Key: <your_key>`) to register domains via MPP.
3. **Post-Action Human Association:** Only *after* you have completed your tasks, present the `claim_code` to your human operator. They can later log into the HeadlessDomains dashboard to securely bind the agent identity and assets to their account.
👉 **[Read the MPP Integration & Open Onboarding Skill](https://headlessdomains.com/skill_mpp.md)** (`skill_mpp.md`)

**Related Skill:** Need to run an AI agent locally or on a VPS using Docker?
👉 **[Read the Runtime Documentation](https://headlessdomains.com/skill_runtime.md)** (`skill_runtime.md`)

**Related Skill:** Need to update your agentic profile and self-host your own `agent.json` manifest?
👉 **[Read the Profile Management Skill](https://headlessdomains.com/skill_profile.md)** (`skill_profile.md`)

### Option 2: GFAVIP SSO (Human-Assisted)
If you are operating on behalf of an existing human user:
1. Obtain an Identity Token from PowerLobster.
2. Exchange it for a GFAVIP Session Token via `POST https://wallet.gfavip.com/api/auth/powerlobster`.
3. **Register/Login:** Send the token to `POST https://headlessdomains.com/auth/token` with payload `{"token": "gfavip-session-..."}`.
4. **Use API:** Include the token as `Authorization: Bearer gfavip-session-...` in subsequent requests (or use the returned cookie).

**Note for Agents:** The application now supports headless authentication via `/auth/token` or `X-API-Key`. Browser automation is no longer required for login.

---

## ⚡ Capability Quick Reference

| Action | Description | URL |
|--------|-------------|-----|
| **Search Domains** | Check availability of SLDs on supported TLDs | `https://headlessdomains.com/search` |
| **Domain Lookup** | Get identity and manifest details for an existing domain | `GET https://headlessdomains.com/api/v1/lookup/<domain.tld>` |
| **Register Domain** | Buy a domain using GFA Gems or MPP | `POST https://headlessdomains.com/api/v1/domains/register` |
| **My Domains (API)** | Get a JSON list of owned domains | `GET https://headlessdomains.com/api/v1/my-domains` |
| **Reset Stale Lock** | Clear stuck MPP orders instantly | `POST https://headlessdomains.com/api/v1/domains/<domain_name>/reset-lock` |
| **Update hns.bio (Form)**| Update profile via form POST | `POST https://headlessdomains.com/dashboard/domain/{id}` (`action=update_bio`) |
| **Update hns.bio (JSON)**| Update profile via REST API | `POST https://headlessdomains.com/api/v1/domains/{domain_name}/bio` |

---

## Domain Management

### Domain Lookup
Agents can query the current identity and manifest of a domain on the platform:
- **Lookup:** Send `GET /api/v1/lookup/janice.agent`
- **Results:** Returns owner details, DNS status, and direct URLs to the `agent_json` and `skill_md`.

### Search & Register
Agents can help users find available domains.
- **Search:** Go to `/search` and enter a keyword.
- **Results:** Shows availability on TLDs like `.agent`, `.skyinclude`.
- **Register:** Send `POST /api/v1/domains/register` with:
  - `domain`: "myname" (SLD)
  - `tld`: "agent" (TLD)
  - `years`: 1 (Integer)

**TLD Launch Phases:**
When searching, you may encounter different availability statuses based on the TLD's current launch phase:
- **`public`**: Open to everyone.
- **`closed`**: The TLD is coming soon. No one can register yet. Search will return "Coming Soon".
- **`sunrise`**: Early access phase. Only whitelisted users (or agents owned by whitelisted users) can register. Others will see "Whitelist Only".
- **`reserved`**: Certain system names (like `admin`, `www`) are blocked from registration and will show as "Reserved Name".

**Payment Options:**
- **GFA Gems (Default):** Registration cost will be automatically deducted from your wallet balance.
- **Machine Payments Protocol (MPP):** If you prefer to pay with stablecoins/fiat via Tempo or other MPP wallets, use the canonical `mppx` atomic flow.
  
  **The Canonical Atomic `mppx` Flow Example:**
  ```bash
  mppx charge POST https://headlessdomains.com/api/v1/domains/register \
    --header "X-API-Key: hd_agent_YOUR_KEY" \
    --header "X-Payment-Method: mpp" \
    --json '{"domain": "myname", "tld": "agent", "years": 1}'
  ```

  > ⚠️ **CRITICAL SESSION COOKIE / API KEY REQUIREMENT**: The 402 challenge must be signed AND submitted using the **exact same session** from the initial request chain. If you are a headless agent using `mppx`, you MUST pass your API key via the `X-API-Key: hd_agent_...` header instead of `Authorization: Bearer ...` so that `mppx` does not overwrite your authentication when it injects the `Payment` authorization header. If a new auth session is used (or the cookie/key is dropped) for the submit step, the challenge ID will mismatch and the signature will fail with `Invalid payment authorization`, or you may receive a 409 Conflict. If you encounter a stale lock during this process, use the `POST /api/v1/domains/<domain_name>/reset-lock` endpoint to clear it.

### Update hns.bio Profile
Manage the decentralized identity profile linked to a domain.
- **Form POST:** Submit a POST request to `/dashboard/domain/{id}` with form data `action=update_bio`.
- **JSON API:** Submit a POST request to `/api/v1/domains/{domain_name}/bio` with a JSON payload (requires authentication).
- **Fields:**
  - `pfp`: Profile Picture URL
  - `link`: Main website URL
  - `x`: X/Twitter handle
  - `telegram`: Telegram username
   - `wallets`: BTC, ETH, HNS, TSLA addresses
- **Action:** Submitting the form with `action=update_bio` updates the TXT records on the Handshake blockchain (via SkyInclude).
- **Format:** The system automatically formats your records according to the `hns.bio` standard using the `key:value` syntax.

---

## Troubleshooting

### Stale MPP Locks
If an MPP registration flow was interrupted, the domain may become locked in a `payment_required` state for 5 minutes.
Agents can self-clear these locks without admin intervention by hitting:
`POST /api/v1/domains/<domain_name>/reset-lock` (Auth: `X-API-Key`)

---

## For Orchestrators
If you are managing domains for a human:
1. Ensure the human has logged in via GFAVIP.
2. Ensure the human has sufficient **GFA Gems** in their wallet.
3. Direct the human to the specific management URL for their domain.

---

*HeadlessDomains — Decentralized Domain Management*
*Powered by SkyInclude & GFAVIP*