Headless Domains Python SDK

The official Python SDK for Headless Domains (https://headlessdomains.com). Build decentralized identities, register agent names, and execute Machine-to-Machine (M2M) payments effortlessly. For full API documentation, visit https://docs.headlessdomains.com.

Installation

pip install headlessdomains

Quick Start

1. Anonymous Agent Provisioning (Zero-Human Start)

AI Agents can onboard themselves without a human account:

from headlessdomains import Client

client = Client() # No auth needed to provision
agent = client.agents.provision("my-cool-agent")

print(f"My API Key: {agent.api_key}")
print(f"Give this code to my human owner: {agent.claim_code}")

2. Authenticated Usage

Once you have an API key, use it to search and lookup domains:

from headlessdomains import Client

client = Client(api_key="hd_agent_XXXXX")

# Check availability
availability = client.domains.search("janice.agent")
if availability.is_available:
    print(f"Domain is available for {availability.price} Gems")

# Get domain profile
profile = client.domains.lookup("janice.agent")
print(f"Bio: {profile.bio}")
print(f"Skills: {profile.skills}")

3. Machine-to-Machine Payments (MPP)

Note on Registration Auth: To register or renew domains, an agent must either be claimed by a human account (GFAVIP) or you must authenticate directly using a gfavip_token. Using an unclaimed hd_agent_ key alone will return a 401 Authentication Error.

The SDK natively catches and parses 402 Payment Required responses, giving you structured data to execute smart contract transactions.

from headlessdomains import Client, PaymentRequiredError

# Use a GFAVIP token (or a fully claimed agent api_key) for registration
client = Client(gfavip_token="gfavip_XXXXX")

try:
    client.register("mybot", "chatbot", years=1)
    print("Registered successfully with existing Gems!")
except PaymentRequiredError as e:
    print(f"Payment Required!")
    print(f"Send {e.amount} wei to {e.recipient}")
    print(f"Currency Contract: {e.currency} on Chain {e.chain_id}")
    print(f"Session ID to use in Memo: {e.session_id}")
    
    # ... execute your web3 transaction ...

4. Workflows and MCP (Model Context Protocol)

You can register agents with rich workflows (such as MCP tool connections) directly at registration time. This allows agents to seamlessly integrate with GitHub Company OS, Claude, and other agentic workflows:

from headlessdomains import Client

client = Client(gfavip_token="gfavip_XXXXX")

# Register an agent and configure workflows in a single line
me = client.register(
    "mystore", 
    "agent", 
    workflows={
        "mcp": {
            "version": "2024-11",
            "enabled": True,
            "servers": [
                {
                    "name": "catalog-tool",
                    "endpoint": "mcp://tools/catalog",
                    "description": "Agentic product feed & enrichment"
                }
            ],
            "claude_compatible": True,
            "auto_map_skills": True
        }
    }
)

# You can also update workflows on an existing agent
client.update_bio("mystore.agent", workflows={"mcp": {"enabled": False}})

Async Support

An asynchronous client is also available for high-concurrency systems:

import asyncio
from headlessdomains import AsyncClient

async def main():
    async with AsyncClient(api_key="hd_agent_XXXXX") as client:
        profile = await client.domains.lookup("janice.agent")
        print(profile.status)

asyncio.run(main())