---
name: headlessdomains
version: 1.0.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 (GFAVIP SSO)

## 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).

**Related Skill:** Need to resolve HNS domains (look up records)?
👉 **[Read the Handshake Resolution Skill](https://headlessdomains.com/skill_hns.md)** (`skill_hns.md`)

## Authentication
This application uses **GFAVIP SSO**. 
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`. 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` |
| **Register Domain** | Buy a domain using GFA Gems | `https://headlessdomains.com/register` (POST) |
| **Manage Domains** | View owned domains and expiry | `https://headlessdomains.com/dashboard` |
| **Update hns.bio** | Update profile picture, links, and wallets | `https://headlessdomains.com/dashboard/domain/{id}` |
| **Admin Dashboard** | Manage TLDs (Team Tier only) | `https://headlessdomains.com/admin` |

---

## Domain Management

### 1. Search & Register
Agents can help users find available domains.
- **Search:** Go to `/search` and enter a keyword.
- **Results:** Shows availability on TLDs like `.chatbot`, `.skyinclude`.
- **Register:** Send `POST /register` with:
  - `domain`: "myname" (SLD)
  - `tld`: "chatbot" (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:
  1. Add header: `X-Payment-Method: mpp` to your `POST /register` request.
  2. The server will return a `402 Payment Required` with an MPP session payload (`session_id`, `pay_url`).
  3. Execute the payment using your wallet.
  4. Submit the receipt to `POST /verify-mpp` with payload: `{"session_id": "...", "receipt": "...", "domain": "myname", "tld": "chatbot", "years": 1, "action": "register"}`.

### 2. Update hns.bio Profile
Manage the decentralized identity profile linked to a domain.
- **Fields:**
  - `pfp`: Profile Picture URL
  - `link`: Main website URL
  - `twitter`: Twitter handle
  - `telegram`: Telegram username
  - `wallets`: BTC, ETH, HNS addresses
- **Action:** Submitting the form updates the TXT records on the Handshake blockchain (via SkyInclude).

---

## 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*