# AgentDomain API Guide

> Domain registration API for AI agents. Search, buy, and manage domains autonomously.

## Two ways to use AgentDomain

### 1. MCP Server (recommended)

If your agent supports MCP (Model Context Protocol), install the AgentDomain MCP server for native tool access — no HTTP requests needed.

```bash
uvx agentdomain-mcp
```

Your agent calls the `register` tool to create an account — the API key is saved automatically.

**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "agentdomain": {
      "command": "uvx",
      "args": ["agentdomain-mcp"]
    }
  }
}
```

**Hermes Agent** — add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  agentdomain:
    command: "uvx"
    args: ["agentdomain-mcp"]
```

**Available MCP tools:**

| Tool | Description |
|------|-------------|
| `register` | Create account + save API key (call first) |
| `account_info` | Get account details |
| `domain_search` | Search for available domains |
| `domain_check` | Check availability + price |
| `domain_buy` | Register a domain |
| `domain_list` | List your domains |
| `domain_dns_get` | Get DNS records |
| `domain_dns_update` | Update DNS records |
| `domain_transfer` | Get EPP auth code |
| `wallet_balance` | Check balance |
| `wallet_topup` | Create crypto top-up invoice |
| `wallet_transactions` | List recent transactions |

### 2. HTTP API

For agents that don't support MCP, use the REST API directly.

## Base URL

```
https://api.agentdomain.cloud/v1
```

## Authentication

### Register to get an API key

```bash
curl -X POST https://api.agentdomain.cloud/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "YourAgentName",
    "email": "you@example.com",
    "password": "securepass123",
    "payment_mode": "auto",
    "billing": {
      "name": "Your Name",
      "address1": "123 Main St",
      "city": "Anytown",
      "country": "US",
      "postal_code": "12345"
    }
  }'
```

### Use the API key in all requests

```
Authorization: Bearer <your_api_key>
```

## Core Workflow

### 1. Search for domains

```bash
curl "https://api.agentdomain.cloud/v1/domains/search?q=mybrand" \
  -H "Authorization: Bearer <your_api_key>"
```

### 2. Check availability + price

```bash
curl -X POST https://api.agentdomain.cloud/v1/domains/check \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mybrand.com"}'
```

### 3. Top up wallet

```bash
# With crypto (NOWPayments)
curl -X POST https://api.agentdomain.cloud/v1/wallet/topup/crypto \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 5000, "crypto_currency": "USDC"}'
```

### 4. Buy a domain

```bash
curl -X POST https://api.agentdomain.cloud/v1/domains/buy \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mybrand.com", "years": 1}'
```

### 5. Manage DNS

```bash
# Get DNS records
curl https://api.agentdomain.cloud/v1/domains/mybrand.com/dns \
  -H "Authorization: Bearer <your_api_key>"

# Update DNS
curl -X PUT https://api.agentdomain.cloud/v1/domains/mybrand.com/dns \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"records": [{"type": "A", "name": "@", "content": "1.2.3.4", "ttl": 300}]}'
```

### 6. Check wallet balance

```bash
curl https://api.agentdomain.cloud/v1/wallet \
  -H "Authorization: Bearer <your_api_key>"
```

## Endpoints

### Auth

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/v1/auth/register` | Register agent (returns API key) |
| POST | `/v1/auth/login` | Login (returns JWT + API key) |
| GET | `/v1/auth/me` | Current agent info |

### Domains

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/domains/search?q=` | Search available domains |
| POST | `/v1/domains/check` | Check availability + price |
| POST | `/v1/domains/buy` | Register domain |
| GET | `/v1/domains` | List your domains |
| GET | `/v1/domains/{domain}/dns` | Get DNS records |
| PUT | `/v1/domains/{domain}/dns` | Update DNS records |
| POST | `/v1/domains/{domain}/transfer` | Get EPP auth code |

### Wallet

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/v1/wallet` | Check balance |
| POST | `/v1/wallet/topup/crypto` | Top up via crypto (NOWPayments) |
| GET | `/v1/wallet/transactions` | Transaction history |

## Security

- **Spending limits**: Max $50 per purchase, $200/day by default
- **Approval mode**: All purchases require human approval (default)
- **Auto mode**: Agent pays directly from wallet
- **API key**: Shown once on registration — save it
- **Email verification**: Required before purchasing domains

## Pricing

Pay only for what you register. No subscription fees. Crypto payments via NOWPayments.

## Status

- **Landing**: https://agentdomain.cloud/
- **Dashboard**: https://agentdomain.cloud/dashboard/
- **API Health**: https://api.agentdomain.cloud/v1/health
- **MCP Server**: https://github.com/MarsHeer/domainagent/tree/main/mcp-server