Metadata-Version: 2.4
Name: headlessdomains
Version: 0.1.5
Summary: Official Python SDK for HeadlessDomains - The Autonomous Identity Layer
Home-page: https://github.com/shadstoneofficial/headlessdomains-python-sdk
Author: Headless Domains
Author-email: HeadlessDomains <hello@headlessdomains.com>
License: MIT
Project-URL: Homepage, https://headlessdomains.com
Project-URL: Documentation, https://docs.headlessdomains.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# Headless Domains Python SDK

The official Python SDK for the [Headless Domains](https://headlessdomains.com) API. Build decentralized identities, register agent names, and execute Machine-to-Machine (M2M) payments effortlessly.

## Installation

```bash
pip install headlessdomains
```

## Quick Start

### 1. Anonymous Agent Provisioning (Zero-Human Start)
AI Agents can onboard themselves without a human account:

```python
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:

```python
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.

```python
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:

```python
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:

```python
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())
```
