Skip to content

Python SDK

The official Python client for HeadlessDomains.

Installation

pip install headlessdomains

Features

  • Dual Client: Built on httpx, providing both synchronous (client.lookup) and asynchronous (await client.alookup) methods.
  • Frictionless Auth: Supports static API keys (recommended for simple scripts) and GFAVIP Session tokens (recommended for human-backed production squads).
  • Headless Operations: Search, register, look up manifests, and autonomously renew your agent's domain directly via API.

Authentication Examples

You can initialize the client using either a static API Key (recommended for scripts) or a GFAVIP Session token (recommended for production squads with human oversight).

from headlessdomains import HeadlessDomainsClient

# Method 1: Simple Static API Key (from Dashboard)
client = HeadlessDomainsClient(api_key="hd_live_xxxxx")

# Method 2: GFAVIP Session Token
client_gfavip = HeadlessDomainsClient(gfavip_token="eyJhbGciOiJIUzI1...")

Quickstart (Sync)

Recommended for simple scripts and prototyping. 

from headlessdomains import HeadlessDomainsClient

client = HeadlessDomainsClient(api_key="hd_live_xxxxx")

# 1. Search
availability = client.search("mytradingagent")
print(availability)

# 2. Look up an existing agent's identity
info = client.lookup("janice.agent")
print(f"Capabilities: {info['identity']['capabilities_preview']}")

# 3. Register a domain using GFA Gems
result = client.register("mytradingagent", "agent", years=1, payment_method="gems")
print(result)

Advanced: MPP Payment Flow (Async)

When registering a domain using the Machine Payment Protocol (mpp), the API will return a 402 Payment Required status along with a payment session. You must fulfill this session via Tempo and then verify it.

import asyncio
from headlessdomains import HeadlessDomainsClient

async def main():
    client = HeadlessDomainsClient(api_key="hd_live_xxxxx")

    # 1. Request Registration via MPP
    reg_intent = await client.aregister(
        domain="mytradingagent", 
        tld="agent", 
        years=1, 
        payment_method="mpp"
    )

    # reg_intent will contain the MPP session details:
    # { "status": "payment_required", "pay_url": "...", "session_id": "..." }

    # 2. Complete payment via Tempo (pseudo-code)
    # receipt = await my_tempo_wallet.pay(reg_intent['pay_url'])

    # 3. Once registered, agents can autonomously renew themselves!
    renew_result = await client.arenew(
        domain="mytradingagent.agent", 
        years=2, 
        payment_method="mpp",
        receipt="mpp_receipt_xyz"
    )
    print(f"Renewed! New Expiry: {renew_result['domain']['new_expiry_date']}")

    await client.aclose()

asyncio.run(main())

Available Methods

Synchronous Methods

  • search(query: str) -> Dict
  • register(domain: str, tld: str, years: int = 1, payment_method: str = "gems") -> Dict
  • lookup(full_domain: str) -> Dict
  • renew(domain: str, years: int = 1, receipt: str = None, payment_method: str = "mpp") -> Dict

Asynchronous Methods

  • asearch(query: str) -> Dict
  • aregister(domain: str, tld: str, years: int = 1, payment_method: str = "gems") -> Dict
  • alookup(full_domain: str) -> Dict
  • arenew(domain: str, years: int = 1, receipt: str = None, payment_method: str = "mpp") -> Dict