# RobotDomainSearch

> RobotDomainSearch is a domain availability API and toolkit for developers and AI agents. Check domain availability across 511 TLDs, get registration links, and look up ENS names programmatically.

RobotDomainSearch is designed for agent integration. All endpoints return JSON. No authentication required. Rate limited to 60 requests/minute per IP.

## Quick Start

Base URL: https://api.robotdomainsearch.com

Check domain availability:
```
GET https://api.robotdomainsearch.com/v1/check?name=example&tld=com
```

Check multiple TLDs:
```
GET https://api.robotdomainsearch.com/v1/check?name=example&tld=com,net,io,ai
```

Check by category:
```
GET https://api.robotdomainsearch.com/v1/check?name=example&category=technology
```

Response (bulk):
```json
{
  "name": "example",
  "results": [
    {
      "domain": "example.com",
      "tld": "com",
      "available": false,
      "status": ["active"],
      "premium": false,
      "source": "rdap",
      "checkedAt": "2025-02-10T12:00:00Z",
      "responseMs": 180
    }
  ],
  "checked": 4,
  "available": 2,
  "unavailable": 1,
  "errors": 1,
  "totalMs": 250,
  "timestamp": "2025-02-10T12:00:00Z"
}
```

## API Documentation

- [API Overview](/docs/api/): Complete API reference
- [Check Availability](/docs/api/availability/): GET /v1/check - Check domain availability (supports bulk TLD and category)
- [WHOIS Lookup](/docs/api/whois/): GET /v1/whois - WHOIS / RDAP domain lookup
- [Domain Intel](/docs/api/intel/): GET /v1/intel - Domain intelligence (parked detection, screenshots)
- [Auctions](/docs/api/auctions/): GET /v1/auctions - Browse live domain auctions
- [List TLDs](/docs/api/tlds/): GET /v1/tlds - List 511 supported TLDs across 15 categories
- [Register](/docs/api/register/): GET /v1/register - Get registration links
- [Health Check](/docs/api/health/): GET /health - API status and version
- [Trademark Search](/docs/api/trademark/): GET /v1/trademark/search - Search USPTO trademark database (~14M records)
- [Rate Limits](/docs/rate-limits/): Usage limits and quotas
- [Error Codes](/docs/api/errors/): Error response reference
- [Payments](/docs/payments/): Payment integration guide (x402 and MPP)

## Payments

Three endpoints require micropayment. Two payment protocols are supported — same pricing, two independent rails:

| Endpoint | Price |
|----------|-------|
| GET /v1/valuation/{domain} (quick) | $0.02 |
| GET /v1/valuation/{domain} (full) | $0.08 |
| GET /v1/name-search-presence | $0.02 |
| GET /v1/intel | $0.05 |

### x402 (USDC on Base)
- Settlement: Base mainnet (chain ID 8453), USDC
- HTTP mechanism: Custom headers (X-PAYMENT-REQUIREMENTS / X-PAYMENT)
- Facilitator: https://api.cdp.coinbase.com/platform/v2/x402
- SDKs: x402-axios (JS), x402-python, x402-go

### MPP (USDC.e on Tempo)
- Settlement: Tempo (chain ID 4217), USDC.e (bridged USDC, TIP-20)
- HTTP mechanism: Standard HTTP Auth (WWW-Authenticate / Authorization: Payment)
- Spec: draft-ryan-httpauth-payment (IETF)

Both protocols use 402 Payment Required challenge-response. Server returns challenges for both protocols simultaneously. Client picks whichever it supports.

- [Payments Documentation](/docs/payments/): Complete integration guide

## ENS API (Ethereum Name Service)

ENS endpoints are proxied through the main API at `/v1/ens/*`.

Base URL: https://api.robotdomainsearch.com

- [ENS Availability](/docs/api/ens-availability/): GET /v1/ens/check - Check ENS name availability + pricing
- [ENS Metadata](/docs/api/ens-metadata/): GET /v1/ens/metadata - Get ENS metadata (address, avatar, social links)
- [ENS Health](/docs/api/ens-health/): GET /v1/ens/health - ENS service health

## Aftermarket API

Check if a domain is listed for sale on aftermarket marketplaces (Sedo, Dynadot). Aggregates real-time data from multiple providers in parallel.

Base URL: https://api.robotdomainsearch.com

Endpoint:
```
GET https://api.robotdomainsearch.com/v1/aftermarket/{domain}
```

Parameters:
- `sources` (query, optional): Comma-separated list of sources (e.g., "sedo,dynadot")
- `timeout` (query, optional): Per-source timeout in ms (default 5000, max 15000)
- `currency` (query, optional): Preferred currency (default "USD")

Example request:
```
GET https://api.robotdomainsearch.com/v1/aftermarket/premium.com
```

Example response:
```json
{
  "domain": "premium.com",
  "listed": true,
  "summary": {
    "totalSources": 2,
    "sourcesChecked": 2,
    "listedCount": 2,
    "lowestPrice": { "amount": 2500.00, "currency": "USD", "source": "dynadot" }
  },
  "listings": [
    {
      "source": "sedo",
      "platform": "Sedo",
      "status": "listed",
      "saleType": "buyNow",
      "price": { "amount": 2700.00, "currency": "USD" },
      "url": "https://sedo.com/search/details/?domain=premium.com",
      "affiliateUrl": "https://sedo.com/search/details/?domain=premium.com&campaignId=330835"
    }
  ],
  "errors": [],
  "meta": { "totalMs": 455, "cacheHit": false, "cacheTTL": 900 }
}
```

Response fields:
- domain: queried domain (lowercased)
- listed: true if listed on any source
- summary: aggregated overview (totalSources, listedCount, lowestPrice, hasAuction, hasMakeOffer)
- listings[]: per-source listing details (source, platform, status, saleType, price, url, affiliateUrl)
- errors[]: per-source errors with code, message, retryable flag
- meta: totalMs, cacheHit, cacheTTL, affiliateDisclosure

Error codes: not_configured, timeout, rate_limited, auth_error, unavailable
HTTP status: 200 (success/partial), 400 (bad domain), 405 (wrong method), 501 (no sources), 503 (all failed)

Current sources: sedo, dynadot. Coming soon: afternic, dan.com, atom.com, squadhelp.

- [Aftermarket API Reference](/docs/api/aftermarket/): Full endpoint documentation

## Name Search Presence API

Check search engine presence for a name or brand. Returns a 0-100 score indicating
how much existing online presence the name has, plus per-engine results and signals.

Base URL: https://api.robotdomainsearch.com

Endpoint:
```
GET https://api.robotdomainsearch.com/v1/name-search-presence?name={name}
```

Parameters:
- `name` (query, required): Name or brand to search for
- `engines` (query, optional): Comma-separated engines (brave, perplexity)
- `timeout` (query, optional): Per-engine timeout in milliseconds

Example request:
```
GET https://api.robotdomainsearch.com/v1/name-search-presence?name=mycoolstartup
```

Example response:
```json
{
  "name": "mycoolstartup",
  "score": 7,
  "status": "clean",
  "summary": "No significant online presence exists for this name...",
  "engines": [
    {
      "engine": "brave",
      "score": 5,
      "exact_hits": 0,
      "loose_hits": 0,
      "top_matches": [],
      "response_ms": 561
    },
    {
      "engine": "perplexity",
      "score": 8,
      "exact_hits": 0,
      "loose_hits": 0,
      "top_matches": [],
      "response_ms": 518
    }
  ],
  "signals": {
    "exact_phrase_found": false,
    "brand_exists": false,
    "company_exists": false,
    "product_exists": false,
    "domain_registered": false,
    "social_handles_found": [],
    "notable_individuals": []
  },
  "errors": [],
  "total_ms": 2642
}
```

Scoring:
- 0-10: clean — no meaningful presence
- 11-30: low — minor matches, likely safe
- 31-60: medium — some presence, investigate
- 61-100: high — strong existing presence

Response fields:
- name: the searched name
- score: 0-100 presence score
- status: clean/low/medium/high
- summary: AI-generated summary of findings
- engines[]: per-engine results (engine, score, exact_hits, loose_hits, top_matches[], response_ms)
- engines[].top_matches[]: title, url, type, relevance
- signals: brand/presence detection (exact_phrase_found, brand_exists, company_exists, product_exists, domain_registered, social_handles_found)
- errors[]: per-engine errors (engine, message)
- total_ms: total response time

- [Name Search Presence API Reference](/docs/api/name-search-presence/): Full endpoint documentation

## Trademark Search API

Search the entire USPTO trademark database (~14M records). Find trademarks by mark text, owner name, goods/services description, or upcoming renewals. Results include full-text, phonetic, and fuzzy matching with detailed match scoring.

Base URL: https://api.robotdomainsearch.com

Endpoints:
```
GET https://api.robotdomainsearch.com/v1/trademark/search?q={mark}
GET https://api.robotdomainsearch.com/v1/trademark/search/description?q={description}
GET https://api.robotdomainsearch.com/v1/trademark/search/owner?q={owner}
GET https://api.robotdomainsearch.com/v1/trademark/search/expiring?days={days}
GET https://api.robotdomainsearch.com/v1/trademark/search/status
```

Parameters:
- `q` (query, required): Search term (mark text, description, or owner name depending on endpoint)
- `days` (query, required for /expiring): Number of days ahead to search for expiring trademarks
- `limit` (query, optional): Maximum results to return (default: 10)
- `offset` (query, optional): Pagination offset
- `class` (query, optional, /search only): Nice classification number (zero-padded, e.g., `009`)

Example request:
```
GET https://api.robotdomainsearch.com/v1/trademark/search?q=apple&limit=2
```

Example response:
```json
{
  "results": [
    {
      "serial_number": "72368372",
      "mark_text": "APPLE",
      "status_code": "900",
      "filing_date": "1970-08-18T00:00:00Z",
      "registration_date": "1972-02-22T00:00:00Z",
      "renewal_date": "0001-01-01T00:00:00Z",
      "owner_name": "MANN'S BAIT MANUFACTURING CO., INC.",
      "goods_services": "FISHING LURES",
      "class_numbers": ["028"],
      "match_score": 1,
      "match_details": {
        "exact_match": true,
        "phonetic_match": true,
        "fuzzy_distance": 0,
        "jaro_winkler": 1,
        "prefix_match": true,
        "phonetic_codes": "APL",
        "matched_codes": "APL",
        "bleve_score": 0.9296381258870355
      },
      "tsdr_enriched": false
    }
  ],
  "total": 6,
  "limit": 2,
  "offset": 0,
  "query": "apple",
  "took_ms": 7635,
  "index_info": {
    "total_documents": 13931255,
    "last_updated": "2026-03-16T01:51:07Z"
  },
  "disclaimer": "This data is sourced from the USPTO and may not reflect the most recent filings. Not legal advice."
}
```

Response fields:
- results[]: array of trademark results
- results[].serial_number, mark_text, status_code, filing_date, registration_date, renewal_date
- results[].owner_name, goods_services, class_numbers[], match_score, match_details
- match_details: exact_match, phonetic_match, fuzzy_distance, jaro_winkler, prefix_match, phonetic_codes, bleve_score
- total: total matching results
- took_ms: query execution time
- index_info: total_documents, last_updated
- disclaimer: legal disclaimer

Status codes: 602 (abandoned), 700 (registered active), 710 (cancelled), 800 (registered and renewed), 900 (expired)

- [Trademark Search API Reference](/docs/api/trademark/): Full endpoint documentation

## MCP Server

RobotDomainSearch provides an MCP server for AI agent integration:

```
npm install -g @robotdomainsearch/mcp
```

Tools: check_domain, whois_lookup, domain_intel, list_tlds, get_registration_link, search_auctions, ens_check, ens_metadata

- [MCP Setup](/mcp/): Install and configure the RobotDomainSearch MCP server

## Endpoints (Main API)

| Endpoint | Method | Price | Description |
|----------|--------|-------|-------------|
| /v1/check | GET | Free | Check domain availability (params: name, tld, category, domain) |
| /v1/whois | GET | Free | WHOIS / RDAP domain lookup (params: domain) |
| /v1/intel | GET | $0.05 | Domain intelligence — parked detection, screenshot (params: domain) |
| /v1/valuation/{domain} | GET | $0.02/$0.08 | Domain valuation — quick ($0.02) or full ($0.08) (params: tier) |
| /v1/auctions | GET | Free | Browse live domain auctions (params: q, tld, source, min_price, max_price, min_bids, ending_within, sort, quality_min, hot, limit, offset) |
| /v1/tlds | GET | Free | List supported TLDs (params: type, category) |
| /v1/register | GET | Free | Get registration links (params: domain, registrar) |
| /v1/aftermarket/{domain} | GET | Free | Check aftermarket listings (params: sources, timeout, currency) |
| /v1/name-search-presence | GET | $0.02 | Check search engine presence for a name (params: name, engines, timeout) |
| /v1/trademark/search | GET | Free | Search USPTO trademarks by mark text (params: q, limit, offset, class) |
| /v1/trademark/search/description | GET | Free | Search trademarks by goods/services description (params: q, limit, offset) |
| /v1/trademark/search/owner | GET | Free | Search trademarks by owner name (params: q, limit, offset) |
| /v1/trademark/search/expiring | GET | Free | Find trademarks with upcoming renewals (params: days, limit, offset) |
| /v1/trademark/search/status | GET | Free | Trademark index health check |
| /health | GET | Free | API health check |

## Endpoints (ENS API)

| Endpoint | Method | Description |
|----------|--------|-------------|
| /v1/ens/check | GET | Check ENS name availability (params: name) |
| /v1/ens/metadata | GET | Get ENS metadata and records (params: name) |
| /v1/ens/health | GET | ENS service health |

## Supported TLDs

511 TLDs across 15 categories: top20, business, country, creative, education, finance, food, health, realestate, shopping, social, sports, technology, travel, web.

Top 20: com, net, org, io, ai, co, dev, app, xyz, me, tech, info, biz, online, site, store, cloud, shop, digital, bot

## Supported Registrars

- Porkbun (slug: porkbun) - includes estimated pricing
- Namecheap (slug: namecheap)
- GoDaddy (slug: godaddy)

## Quick Reference

- Aftermarket: GET /v1/aftermarket/{domain} — check if listed for sale across marketplaces
- Main API Base URL: https://api.robotdomainsearch.com
- ENS API: proxied via main API at /v1/ens/*
- Auth: None required (3 endpoints require micropayment — see Payments)
- Payment Protocols: x402 (USDC on Base) and MPP (USDC.e on Tempo)
- Format: JSON
- Rate Limit: 60/min per IP
- Max TLDs per request: 20

## Response Fields

/v1/check returns:
- name: domain name checked
- results[]: array of check results
- results[].domain, tld, available, status[], premium, source, checkedAt, responseMs
- Bulk only: checked, available, unavailable, errors
- totalMs: total check time
- timestamp: response timestamp

/v1/tlds returns:
- total: number of TLDs
- categories[]: array of {name, label, description, count, tlds[]}
- all[]: sorted list of all TLD strings (default response)
- tlds[]: array of {tld, type, rdapServer, categories[], enabled} (type filter)

/v1/register returns:
- domain: requested domain
- registrars[]: array of {name, slug, url, estimatedPrice?}
- timestamp: response timestamp

ENS /v1/ens/check returns:
- name: full ENS name (with .eth)
- available: boolean
- owner, resolver: Ethereum addresses (if taken)
- registrationPrice: {wei, eth, usdEstimate} (if available)
- responseMs, source, checkedAt

ENS /metadata returns:
- name, owner, resolver, address
- records: {avatar, url, description, twitter, github, email, contenthash}
- responseMs, source, checkedAt

## OpenAPI Specification

Full OpenAPI 3.0 spec available at: https://robotdomainsearch.com/openapi.yaml