Metadata-Version: 2.4
Name: headlessdomains
Version: 0.1.4
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.domains.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 ...
```

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