agentns-client 0.1.0

Python client for AgentNS - wallet-based ICANN domain registrar for AI agents

AgentNS Python Client

Python client library for AgentNS - a wallet-based ICANN domain registrar for AI agents.

Features

• Wallet Authentication: Sign-In With Ethereum (SIWE) authentication
• Domain Registration: Full x402 payment protocol support with USDC on Base
• DNS Management: Create, update, delete DNS records
• Nameserver Management: Configure custom nameservers
• Type Safety: Full Pydantic models for all API types

Installation

pip install agentns-client

Or install from source:

git clone https://github.com/vibrant/agentns_client.git
cd agentns_client
pip install -e .

Quick Start

from agentns_client import AgentNSClient, load_or_create_wallet

# Create or load wallet
account = load_or_create_wallet()
print(f"Wallet: {account.address}")

# Create client
client = AgentNSClient(account=account)

# Check domain availability (no auth required)
result = client.check_domain("myagent.xyz")
print(f"Available: {result.available}, Price: ${result.price_usdc} USDC")

# Search across TLDs
results = client.search_domains("myagent")
for r in results:
    if r.available:
        print(f"{r.domain}: ${r.price_usdc}")

Full Registration Flow

from agentns_client import AgentNSClient, load_or_create_wallet

account = load_or_create_wallet()

with AgentNSClient(account=account) as client:
    # 1. Check availability
    check = client.check_domain("myagent.xyz")
    if not check.available:
        print("Domain not available")
        exit(1)

    # 2. Authenticate with SIWE
    client.login()

    # 3. Create registrant profile (required by ICANN)
    client.create_registrant({
        "name": "Agent Smith",
        "street_address": "123 AI Street",
        "city": "San Francisco",
        "state_province": "CA",
        "postal_code": "94102",
        "country_code": "US",
        "email": "[e-mail]",
        "phone": "[phone]",
        "whois_privacy": True,
    })

    # 4. Register domain (handles x402 payment automatically)
    domain = client.register_domain("myagent.xyz", years=1)
    print(f"Registered: {domain.domain}")
    print(f"Expires: {domain.expires_at}")

DNS Management

# List DNS records
records = client.list_dns("myagent.xyz")

# Add A record
client.add_dns("myagent.xyz", type="A", host="@", value="192.0.2.1")

# Add CNAME
client.add_dns("myagent.xyz", type="CNAME", host="www", value="myagent.xyz")

# Add MX record
client.add_dns("myagent.xyz", type="MX", host="@", value="mail.example.com", distance=10)

# Update record
client.update_dns("myagent.xyz", record_id="12345", value="192.0.2.2")

# Delete record
client.delete_dns("myagent.xyz", record_id="12345")

Nameserver Management

# Get current nameservers
ns = client.get_nameservers("myagent.xyz")
print(ns)  # ['ns1.namesilo.com', 'ns2.namesilo.com']

# Change to Cloudflare
client.set_nameservers("myagent.xyz", [
    "ns1.cloudflare.com",
    "ns2.cloudflare.com"
])

API Reference

AgentNSClient

client = AgentNSClient(
    base_url="https://agentns.xyz",  # API base URL
    account=account,                   # eth_account.Account
    timeout=60.0,                      # HTTP timeout
)

Public Methods (No Auth Required)

Method	Description
check_domain(domain)	Check availability and price
search_domains(name)	Search across 20 TLDs

Authenticated Methods

Method	Description
login()	Authenticate with SIWE
get_registrant()	Get registrant profile
create_registrant(data)	Create registrant profile
update_registrant(data)	Update registrant profile
list_domains()	List owned domains
register_domain(domain, years)	Register with x402 payment
list_dns(domain)	List DNS records
add_dns(domain, **kwargs)	Add DNS record
update_dns(domain, record_id, **kwargs)	Update DNS record
delete_dns(domain, record_id)	Delete DNS record
get_nameservers(domain)	Get nameservers
set_nameservers(domain, nameservers)	Change nameservers

Exceptions

from agentns_client import (
    AgentNSError,           # Base exception
    AuthenticationError,    # 401 - Auth failed
    PaymentRequiredError,   # 402 - Payment needed
    NotFoundError,          # 404 - Resource not found
    ConflictError,          # 409 - Already exists
    ValidationError,        # 400 - Invalid input
    RateLimitError,         # 429 - Too many requests
    RegistrationFailedError # Registration failed after payment
)

Wallet Utilities

from agentns_client import load_wallet, load_or_create_wallet

# Load existing wallet (fails if not found)
account = load_wallet("path/to/wallet.json")

# Load or create new wallet
account = load_or_create_wallet("path/to/wallet.json")

Payment Details

AgentNS uses the x402 protocol for payments:

• Currency: USDC on Base (Chain ID: 8453)
• Contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• Method: EIP-3009 transferWithAuthorization

The client handles the full payment flow automatically:

1. Request returns 402 with payment requirement
2. Client signs EIP-3009 authorization
3. Client resubmits with X-PAYMENT header
4. Domain is registered atomically with payment

Environment Variables

Variable	Description	Default
AGENTNS_API	API base URL	https://agentns.xyz

License

MIT License - see LICENSE for details.

Links

• AgentNS Website
• API Documentation
• GitHub Issues