# BrokerClaw — Domain Brokerage MCP Server

> BrokerClaw is an MCP (Model Context Protocol) server that provides domain name brokerage services to AI agent clients. Agents connect, research domains, get valuations and recommendations, report purchases and sales, and the broker tracks 5% commission on all transactions.

## What This Service Does

BrokerClaw acts as a domain broker for AI agents. It provides 15 MCP tools across 6 categories:

### Client Management
- `register_client` — Register an agent with name, budget, preferences, and autonomy level. Returns a clientId.
- `update_preferences` — Update budget, TLD preferences, keywords, or autonomy settings.
- `get_client_profile` — View profile, remaining budget, and current settings.

### Research & Discovery
- `check_availability` — Check domain availability using RDAP + multi-provider DNS (Cloudflare, Google, Quad9, OpenDNS).
- `search_domains` — Search for available domains by keyword, TLDs, price range, and length. Respects client preferences.
- `whois_lookup` — WHOIS lookup via Whoxy API returning registrar, dates, nameservers, and status.

### Valuation & Analysis
- `valuate_domain` — Estimate domain market value using GoDaddy GoValue API with heuristic fallback.
- `analyze_domain` — Score domain brandability, memorability, pronounceability, and pattern characteristics.

### Recommendations
- `get_recommendations` — Get personalized domain picks based on client preferences and optional focus area.
- `get_market_opportunities` — Discover undervalued and trending domains.

### Transaction Tracking (5% Commission)
- `report_purchase` — Report a domain purchase. Broker tracks 5% commission.
- `report_sale` — Report a domain sale. Broker tracks 5% commission.
- `get_commission_report` — View commission balance and transaction history.
- `get_portfolio_summary` — View all domains the broker helped acquire and sell.

### Marketplace
- `generate_listing` — Generate Afternic CSV, Sedo CSV, or general listing copy.

## How to Connect

Add to your agent's MCP configuration (`.mcp.json`):

```json
{
  "mcpServers": {
    "brokerclaw": {
      "command": "node",
      "args": ["path/to/claw/dist/index.js"]
    }
  }
}
```

Transports: stdio (default, for local agents) or SSE (for remote agents over HTTP).

## Client Autonomy System

Each agent sets an autonomy level at registration:
- `fully_autonomous` — Agent acts on recommendations without human approval.
- `human_in_the_loop` — Agent always asks its human before acting.
- `mixed` — Auto-approve purchases below `autonomyBudgetThreshold`, ask human above.

Recommendations include autonomy metadata so the agent knows how to proceed.

## Commission Model

- Rate: 5% on all reported purchases and sales.
- Storage: Append-only JSONL ledger.
- v1: Track only — no payment collection.

## Typical Agent Flow

1. Call `register_client` with name, budget, preferences → get clientId
2. Call `search_domains` or `get_recommendations` → find domains
3. Call `analyze_domain` + `valuate_domain` → evaluate quality and value
4. Make purchase decision based on autonomy level
5. Call `report_purchase` → 5% commission tracked
6. Call `get_commission_report` or `get_portfolio_summary` → review activity

## Payment (x402)

The SSE transport is gated with the x402 protocol. Remote agent clients pay per-request in USDC on Base.

- Protocol: x402 (HTTP 402 payment flow)
- Token: USDC
- Networks: Base (eip155:8453), Base Sepolia (eip155:84532)
- Price: $0.001 per request (GET /sse + POST /messages)
- A full research flow (check + analyze + valuate) costs ~$0.004
- /health is always free (no payment required)
- Stdio transport is always free (local usage)
- When X402_PAY_TO is unset on the server, payment gating is disabled

Agents must include an x402 payment header with each request. The payment is verified by a facilitator (x402.org for testnet, x402.coinbase.com for mainnet) before the request is processed.

## Technical Details

- Runtime: Node.js 18+
- Language: TypeScript
- Protocol: Model Context Protocol (MCP)
- Data: JSON file-based persistence (clients, transactions, commissions)
- Caching: In-memory TTL cache for DNS, RDAP, WHOIS, and valuations
- TLDs with pricing data: com, net, org, io, ai, xyz, co, app, dev, bot