# AgentNS - Domain Registration for AI Agents

AgentNS is the first ICANN domain registrar built for AI agents. Authenticate with your wallet, pay with USDC, register domains instantly.

**For AI agents:** Use the [skill file](https://agentns.xyz/static/skills/agentns/SKILL.md) for complete setup instructions.

---

## Installation

```bash
pip install agentns-client

# For Solana wallet support:
pip install agentns-client[solana]
```

---

## Quick Start

```python
from agentns_client import AgentNSClient, load_or_create_wallet

# Create client with wallet
account = load_or_create_wallet()
client = AgentNSClient(account=account)

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

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

# Authenticate
client.login()

# Create registrant profile (one-time, ICANN requirement)
client.ensure_registrant({
    "name": "Agent Smith",
    "street_address": "123 AI Street",
    "city": "San Francisco",
    "state_province": "CA",
    "postal_code": "94102",
    "country_code": "US",
    "email": "contact@agentns.xyz",
    "phone": "+14155551234",
})

# Register domain (payment handled automatically)
domain = client.register_domain("myagent.xyz")
print(f"Registered: {domain.domain}, Expires: {domain.expires_at}")

# Manage DNS
client.add_dns("myagent.xyz", type="A", host="@", value="192.0.2.1")
client.add_dns("myagent.xyz", type="CNAME", host="www", value="myagent.xyz")
```

---

## Client Methods

### Domains

| Method | Auth | Description |
|--------|------|-------------|
| `check_domain(domain)` | No | Check single domain availability and price |
| `search_domains(name)` | No | Search across 20 TLDs (com, io, net, co, ai, xyz, dev, app, org, tech, club, online, site, info, me, biz, us, cc, tv, gg) |
| `register_domain(domain, years=1)` | Yes | Register domain (1-10 years) |
| `list_domains()` | Yes | List domains owned by wallet |

### DNS

| Method | Description |
|--------|-------------|
| `list_dns(domain)` | List all DNS records |
| `add_dns(domain, type, host, value, ttl=3600, distance=None)` | Add record (A, AAAA, CNAME, MX, TXT, SRV, CAA) |
| `update_dns(domain, record_id, host=None, value=None, ttl=None)` | Update record |
| `delete_dns(domain, record_id)` | Delete record |
| `get_nameservers(domain)` | Get current nameservers |
| `set_nameservers(domain, nameservers)` | Change nameservers (2-13 required) |

### Registrant

| Method | Description |
|--------|-------------|
| `get_registrant()` | Get registrant profile |
| `create_registrant(data)` | Create profile (required before first registration) |
| `update_registrant(data)` | Update profile fields |
| `ensure_registrant(data)` | Get existing or create new profile |

---

## Registrant Fields

ICANN requires contact information for domain registration. Create once per wallet.

| Field | Required | Example |
|-------|----------|---------|
| `name` | Yes | "Agent Smith" |
| `street_address` | Yes | "123 Main St" |
| `city` | Yes | "San Francisco" |
| `state_province` | Yes | "CA" |
| `postal_code` | Yes | "94102" |
| `country_code` | Yes | "US" (ISO 3166-1 alpha-2) |
| `email` | Yes | "agent@example.com" |
| `phone` | Yes | "+14155551234" |
| `organization` | No | "AI Corp" |
| `whois_privacy` | No | `true` (default) |

---

## Error Handling

```python
from agentns_client.exceptions import (
    AuthenticationError,    # 401 - Invalid/expired JWT
    PaymentRequiredError,   # 402 - Insufficient USDC
    NotFoundError,          # 404 - Domain/record not found
    ConflictError,          # 409 - Already exists
    ValidationError,        # 400 - Invalid input
    RateLimitError,         # 429 - Too many requests
)

try:
    domain = client.register_domain("example.xyz")
except PaymentRequiredError:
    print("Fund wallet with USDC on Base network")
except ConflictError:
    print("Domain unavailable")
```

---

## Payment

- **Currency:** USDC on Base (EVM) or Solana
- **Pricing:** Domain cost + 20% markup (minimum $4)
- **Settlement:** Atomic - payment only succeeds if registration succeeds

Fund your wallet before registering:
- **EVM:** Send USDC to wallet address on Base (chain ID 8453)
- **Solana:** Send USDC to wallet address on Solana mainnet

---

## Links

- **Skill File:** [https://agentns.xyz/static/skills/agentns/SKILL.md](https://agentns.xyz/static/skills/agentns/SKILL.md)
- **Full API Reference:** [https://agentns.xyz/docs](https://agentns.xyz/docs)
- **PyPI:** https://pypi.org/project/agentns-client/
- **GitHub:** https://github.com/vibrant/agentns_client
- **Support:** [@AgentNSxyz](https://x.com/AgentNSxyz)