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.
pip install headlessdomainsAI 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}")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}")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 ...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}})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())