# RobotDomainSearch — Full Tool Reference

> Complete tool schemas, parameters, and examples for all RobotDomainSearch MCP tools and API endpoints.

Base URL: https://api.robotdomainsearch.com
Rate Limit: 60 requests/minute per IP
Format: JSON

## Authentication & Pricing

Most endpoints are free. Three endpoints require micropayment via one of two supported protocols — **x402** (USDC on Base) or **MPP** (USDC.e on Tempo). Same pricing, two independent payment rails. No API key, no subscription, no registration — just pay per request.

### Paid Endpoints

| Endpoint | Price | Description |
|----------|-------|-------------|
| GET /v1/valuation/{domain} | $0.02 (quick) / $0.08 (full) | Domain valuation |
| GET /v1/name-search-presence | $0.02 | Name/brand search presence |
| GET /v1/intel | $0.05 | Domain intelligence report |

### Dual Challenge

When you request a paid endpoint without payment credentials, the server returns `402 Payment Required` with challenges for **both** protocols simultaneously:

```
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="abc123...", realm="robotdomainsearch.com",
  method="tempo", intent="charge", request="eyJhbW91bnQiOiIyMDAwMCI..."
X-PAYMENT-REQUIREMENTS: eyJwcmljZSI6IjAuMDIiLCJjdXJyZW5jeSI6IlVTREMi...
Cache-Control: no-store
```

- `WWW-Authenticate: Payment ...` → MPP challenge (Tempo)
- `X-PAYMENT-REQUIREMENTS: ...` → x402 challenge (Base)

Your agent reads whichever header it understands and pays via that protocol. Same price either way.

### x402 (USDC on Base)

Settlement on Base (chain ID 8453) using USDC.

**Payment Flow:**
1. Request a paid endpoint without payment headers
2. Server returns `402 Payment Required` with `X-PAYMENT-REQUIREMENTS` header containing amount, recipient, and network
3. Client signs a USDC payment on Base (handled by x402 SDK)
4. Client re-sends the request with `X-PAYMENT` header containing the signed payment
5. Server verifies payment via facilitator and returns data

**Payment Details:**
- Network: Base mainnet (chain ID 8453)
- Token: USDC
- Wallet: `0xC06c0B4Ab2e9B5fC64C88c29A1D6CEA1661390Bc`
- Facilitator URL: `https://api.cdp.coinbase.com/platform/v2/x402`
- Max Timeout: 60 seconds
- SDKs: x402-axios (JS), x402-python, x402-go

### MPP (USDC.e on Tempo)

Settlement on Tempo (chain ID 4217) using USDC.e (bridged USDC, TIP-20 token). MPP uses standard HTTP Authentication (`WWW-Authenticate` / `Authorization`) — formally specified as the "Payment" HTTP Authentication Scheme in [draft-ryan-httpauth-payment](https://datatracker.ietf.org/doc/draft-ryan-httpauth-payment/).

**Payment Flow (5 steps):**

1. **Get the challenge** — Request a paid endpoint without credentials. Server responds with `402 Payment Required` and a `WWW-Authenticate` header:
   ```
   WWW-Authenticate: Payment id="abc123...", realm="robotdomainsearch.com",
     method="tempo", intent="charge", request="eyJhbW91bnQiOiIyMDAwMCI..."
   ```

2. **Decode the challenge** — Base64url-decode the `request` parameter:
   ```json
   {
     "amount": "20000",
     "currency": "0x20c0000000000000...b9537d11c60e8b50",
     "recipient": "0xYourRecipientAddress",
     "methodDetails": { "chainId": 4217 }
   }
   ```
   - `amount` — In the token's smallest unit (6 decimals). `20000` = $0.02.
   - `currency` — The USDC.e contract address on Tempo.
   - `recipient` — The address to pay.
   - `chainId` — 4217 (Tempo mainnet).

3. **Create payment on Tempo** — Transfer USDC.e (TIP-20 token, equivalent to ERC-20) on the Tempo blockchain for the specified amount to the specified recipient. Tempo is EVM-compatible.

4. **Build and send credential** — Retry the original request with an `Authorization: Payment` header containing a base64url-encoded credential:
   ```
   Authorization: Payment eyJjaGFsbGVuZ2UiOnsiaWQiOiJhYmMxMjMuLi4i...
   ```
   Decoded credential JSON:
   ```json
   {
     "challenge": {
       "id": "abc123...",
       "realm": "robotdomainsearch.com",
       "method": "tempo",
       "intent": "charge",
       "request": "eyJhbW91bnQiOiIyMDAwMCI..."
     },
     "payload": {
       "type": "hash",
       "hash": "0x7a3f..."
     }
   }
   ```

5. **Receive data + receipt** — Server verifies the HMAC-bound challenge ID and on-chain payment, returns data with a `Payment-Receipt` header.

**Key Details:**
- Token: USDC.e — bridged USDC, TIP-20 standard (equivalent to ERC-20), 6 decimals
- Chain: Tempo — chain ID 4217, EVM-compatible
- Challenge binding: HMAC-SHA256 — stateless, tamper-proof
- Payment modes: Push (client broadcasts tx, sends hash) or Pull (client signs tx, server broadcasts)

### x402 vs MPP Comparison

| Feature | x402 | MPP |
|---------|------|-----|
| Settlement chain | Base (chain ID 8453) | Tempo (chain ID 4217) |
| Token | USDC | USDC.e (bridged USDC) |
| HTTP mechanism | Custom headers (`X-PAYMENT-REQUIREMENTS` / `X-PAYMENT`) | Standard HTTP Auth (`WWW-Authenticate` / `Authorization`) |
| Challenge binding | Implicit (per route) | HMAC-bound challenge IDs |
| Error format | JSON response body | RFC 9457 Problem Details |
| Spec | [x402.org](https://www.x402.org/) | [IETF draft](https://datatracker.ietf.org/doc/draft-ryan-httpauth-payment/) |
| Ecosystem | Coinbase / Base | Tempo |

### MPP Error Types

MPP errors follow RFC 9457 Problem Details format:

| Error Type | Meaning |
|------------|---------|
| `payment-required` | No credential provided |
| `payment-insufficient` | Amount too low |
| `payment-expired` | Challenge expired |
| `verification-failed` | On-chain verification failed |
| `invalid-challenge` | HMAC verification failed (tampering detected) |
| `malformed-credential` | Could not decode credential |

Every MPP error response includes a fresh `WWW-Authenticate` challenge header, so the client can immediately retry without a separate request.

### Payment Receipt

Successful MPP payments return a `Payment-Receipt` header confirming the transaction:

```
Payment-Receipt: eyJtZXRob2QiOiJ0ZW1wbyIsInJlZmVyZW5jZSI6IjB4...
```

Base64url-decoded:
```json
{
  "method": "tempo",
  "reference": "0x7a3f...",
  "status": "success"
}
```

This provides cryptographic proof of the exchange — useful for audit trails and dispute resolution.

---

## MCP Tools

### check_domain

Check if a single domain is available for registration.

Parameters:
- name (string, required): Domain name without TLD (e.g. "myapp")
- tld (string, optional): TLD to check (default: "com")

Example request:
```
check_domain({ name: "mycoolstartup", tld: "io" })
```

Example response:
```json
{
  "domain": "mycoolstartup.io",
  "tld": "io",
  "available": true,
  "status": [],
  "premium": false,
  "source": "rdap",
  "checkedAt": "2025-02-10T12:00:00Z",
  "responseMs": 45
}
```

API equivalent: GET /v1/check?name=mycoolstartup&tld=io

---

### whois_lookup

Look up WHOIS/RDAP registration data for a domain.

Parameters:
- domain (string, required): Full domain name (e.g. "example.com")

Example request:
```
whois_lookup({ domain: "example.com" })
```

Example response:
```json
{
  "domain": "example.com",
  "registrar": "RESERVED-Internet Assigned Numbers Authority",
  "createdDate": "1995-08-14T04:00:00Z",
  "expiryDate": "2025-08-13T04:00:00Z",
  "updatedDate": "2024-08-14T07:01:38Z",
  "status": ["clientDeleteProhibited", "clientTransferProhibited"],
  "nameservers": ["a.iana-servers.net", "b.iana-servers.net"],
  "source": "rdap",
  "responseMs": 120
}
```

API equivalent: GET /v1/whois?domain=example.com

---

### domain_intel

Get domain intelligence including parked detection and screenshots.

**💰 Paid endpoint: $0.05 via x402 or MPP**

Parameters:
- domain (string, required): Full domain name (e.g. "example.com")

Example request:
```
domain_intel({ domain: "parked-domain.com" })
```

Example response:
```json
{
  "domain": "parked-domain.com",
  "parked": true,
  "parkedConfidence": 0.95,
  "title": "This domain is for sale",
  "screenshotUrl": "https://api.robotdomainsearch.com/screenshots/parked-domain.com.png",
  "redirectChain": [],
  "responseMs": 2500
}
```

API equivalent: GET /v1/intel?domain=parked-domain.com

---

### domain_valuation

Get AI-powered domain valuation with price estimates and comparable sales.

**💰 Paid endpoint: $0.02 (quick) / $0.08 (full) via x402 or MPP**

Parameters:
- domain (string, required): Full domain name (e.g. "startup.com")
- tier (string, optional): Valuation depth — "quick" (default, ~8s) or "full" (~20s)

Example request:
```
domain_valuation({ domain: "startup.com", tier: "quick" })
```

Example response:
```json
{
  "domain": "startup.com",
  "tier": "quick",
  "estimate": {
    "low": 15000,
    "mid": 45000,
    "high": 120000,
    "currency": "USD"
  },
  "confidence": 72,
  "explanation": "Premium single-word .com domain with strong business appeal...",
  "key_factors": [
    "Single dictionary word",
    "High-value .com TLD",
    "Strong commercial intent"
  ],
  "heuristic": {
    "length_score": 85,
    "tld_score": 100,
    "word_score": 95,
    "pattern": "dictionary-word",
    "pronounceability": 90,
    "penalties": [],
    "range_low": 10000,
    "range_high": 100000
  },
  "comparables": [
    {
      "domain": "founder.com",
      "sale_price": 50000,
      "sale_date": "2024-03-15",
      "venue": "Sedo",
      "similarity_tier": 1,
      "similarity_score": 0.82
    }
  ],
  "statistical_anchors": {
    "tld": "com",
    "pattern": "dictionary-word",
    "length_range": "7-7",
    "median": 35000,
    "mean": 48000,
    "p25": 12000,
    "p75": 75000,
    "count": 847
  },
  "data_sources": {
    "rdap": true,
    "dns": true,
    "search": true,
    "comparables_found": 5,
    "agent_used": true
  },
  "cached": false,
  "timestamp": "2025-02-10T12:00:00Z"
}
```

API equivalent: GET /v1/valuation/startup.com?tier=quick

---

### list_tlds

Get all 511+ supported top-level domains, optionally filtered by category or type.

Parameters:
- category (string, optional): Filter by category (technology, business, creative, country, education, finance, food, health, realestate, shopping, social, sports, travel, web, top20)
- type (string, optional): Filter by type (generic, country, new)

Example request:
```
list_tlds({ category: "technology" })
```

Example response:
```json
{
  "total": 25,
  "categories": [
    {
      "name": "technology",
      "label": "Technology",
      "description": "Tech-focused TLDs",
      "count": 25,
      "tlds": ["ai", "app", "bot", "cloud", "codes", "dev", "digital", "io", "tech", "software"]
    }
  ]
}
```

API equivalent: GET /v1/tlds?category=technology

---

### get_registration_link

Get registrar links to register available domains.

Parameters:
- domain (string, required): Full domain name (e.g. "myapp.dev")
- registrar (string, optional): Preferred registrar — "porkbun", "namecheap", or "godaddy"

Example request:
```
get_registration_link({ domain: "myapp.dev", registrar: "porkbun" })
```

Example response:
```json
{
  "domain": "myapp.dev",
  "registrars": [
    {
      "name": "Porkbun",
      "slug": "porkbun",
      "url": "https://porkbun.com/checkout/search?q=myapp.dev",
      "estimatedPrice": "$9.73/yr"
    }
  ],
  "timestamp": "2025-02-10T12:00:00Z"
}
```

API equivalent: GET /v1/register?domain=myapp.dev&registrar=porkbun

---

### search_auctions

Browse live domain auctions from multiple marketplaces.

Parameters:
- q (string, optional): Search keyword
- tld (string, optional): Filter by TLD (e.g. "com", "ai")
- source (string, optional): Filter by source (e.g. "namecheap", "sedo", "dynadot")
- min_price (number, optional): Minimum price filter
- max_price (number, optional): Maximum price filter
- min_bids (number, optional): Minimum bid count
- ending_within (string, optional): Time filter (e.g. "1h", "24h", "7d")
- sort (string, optional): Sort field (e.g. "end_time", "price", "bids")
- quality_min (number, optional): Minimum quality score (0-100)
- hot (boolean, optional): Only show hot/trending auctions
- limit (number, optional): Results per page (default 20, max 100)
- offset (number, optional): Pagination offset

Example request:
```
search_auctions({ q: "crypto", tld: "com", max_price: 500, ending_within: "24h" })
```

Example response:
```json
{
  "auctions": [
    {
      "domain": "cryptowidget.com",
      "source": "namecheap",
      "currentBid": 125.00,
      "bids": 8,
      "endTime": "2025-02-10T18:00:00Z",
      "url": "https://www.namecheap.com/domains/auction/...",
      "quality": 72
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}
```

API equivalent: GET /v1/auctions?q=crypto&tld=com&max_price=500&ending_within=24h

---

### ens_check

Check ENS (.eth) name availability and pricing.

Parameters:
- name (string, required): ENS name with or without .eth (e.g. "vitalik" or "vitalik.eth")

Example request:
```
ens_check({ name: "mycoolname" })
```

Example response:
```json
{
  "name": "mycoolname.eth",
  "available": true,
  "registrationPrice": {
    "wei": "3168808781402",
    "eth": "0.000003168808781402",
    "usdEstimate": "$0.01"
  },
  "responseMs": 350,
  "source": "ens-sdk",
  "checkedAt": "2025-02-10T12:00:00Z"
}
```

API equivalent: GET /v1/ens/check?name=mycoolname

---

### ens_metadata

Get ENS metadata including address, avatar, and social records.

Parameters:
- name (string, required): ENS name with or without .eth (e.g. "nick" or "nick.eth")

Example request:
```
ens_metadata({ name: "nick.eth" })
```

Example response:
```json
{
  "name": "nick.eth",
  "owner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
  "resolver": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41",
  "address": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
  "records": {
    "avatar": "eip155:1/erc1155:0x...",
    "url": "https://nick.eth.limo",
    "description": "Lead developer of ENS",
    "twitter": "nicksdjohnson",
    "github": "arachnid",
    "email": null,
    "contenthash": "ipfs://Qm..."
  },
  "responseMs": 280,
  "source": "ens-sdk",
  "checkedAt": "2025-02-10T12:00:00Z"
}
```

API equivalent: GET /v1/ens/metadata?name=nick.eth

---

## Additional API Endpoints

### Domain Valuation

**💰 Paid endpoint: $0.02 (quick) / $0.08 (full) via x402 or MPP**

Get AI-powered domain valuation with comparable sales analysis.

```
GET /v1/valuation/{domain}
```

Parameters:
- domain (path, required): Full domain name (e.g. "startup.com")
- tier (query, optional): "quick" (default, $0.02) or "full" ($0.08)

**Quick tier (~8s):** Heuristic analysis + basic AI assessment
**Full tier (~20s):** Deep analysis with comparable sales, statistical anchors, and detailed explanation

Response fields:
- `domain` (string): Domain analyzed
- `tier` (string): "quick" or "full"
- `estimate` (object): `low`, `mid`, `high` values in USD, plus `currency`
- `confidence` (integer): 0-100 confidence score
- `explanation` (string): AI-generated valuation rationale
- `key_factors` (array): Main factors affecting value
- `heuristic` (object): Scoring breakdown — `length_score`, `tld_score`, `word_score`, `pattern`, `pronounceability`, `penalties`, `range_low`, `range_high`
- `comparables` (array): Similar domain sales — `domain`, `sale_price`, `sale_date`, `venue`, `similarity_tier`, `similarity_score`
- `statistical_anchors` (object): Market stats for similar domains — `tld`, `pattern`, `length_range`, `median`, `mean`, `p25`, `p75`, `count`
- `data_sources` (object): Sources used — `rdap`, `dns`, `search`, `comparables_found`, `agent_used`, `agent_error`
- `cached` (boolean): Whether result was cached
- `timestamp` (string): ISO 8601 timestamp

Errors:
| Code | Error | Description |
|------|-------|-------------|
| 400 | missing_domain | Domain path parameter required |
| 400 | invalid_domain | Domain must include TLD |
| 400 | invalid_tier | Tier must be "quick" or "full" |
| 402 | payment_required | x402 payment required |
| 503 | service_unavailable | Valuation engine not initialized |

---

### Aftermarket Search

Check if a domain is listed for sale on aftermarket marketplaces.

```
GET /v1/aftermarket/{domain}
```

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

---

### Name Search Presence

**💰 Paid endpoint: $0.02 via x402 or MPP**

Check search engine presence for a name or brand.

```
GET /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

Returns a 0-100 presence score:
- 0-10: clean (no meaningful presence)
- 11-30: low (minor matches)
- 31-60: medium (some presence)
- 61-100: high (strong existing presence)

---

### Trademark Search

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

**5 Endpoints:**

#### Search by Mark Text

```
GET /v1/trademark/search
```

Parameters:
- q (string, required): Trademark text to search for (e.g., "apple")
- limit (integer, optional): Maximum results to return (default: 10)
- offset (integer, optional): Number of results to skip for pagination
- class (string, optional): Filter by 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
    },
    {
      "serial_number": "72425692",
      "mark_text": "APPLE",
      "status_code": "710",
      "filing_date": "1972-05-26T00:00:00Z",
      "registration_date": "1973-06-26T00:00:00Z",
      "renewal_date": "0001-01-01T00:00:00Z",
      "owner_name": "JOHN MIDDLETON CO.",
      "goods_services": "SMOKING TOBACCO",
      "class_numbers": ["034"],
      "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."
}
```

---

#### Search by Goods/Services Description

```
GET /v1/trademark/search/description
```

Parameters:
- q (string, required): Goods/services description to search for (e.g., "software")
- limit (integer, optional): Maximum results to return (default: 10)
- offset (integer, optional): Number of results to skip for pagination

Example request:
```
GET https://api.robotdomainsearch.com/v1/trademark/search/description?q=software&limit=1
```

Example response:
```json
{
  "results": [
    {
      "serial_number": "77943993",
      "mark_text": "TWAIN CERTIFIED",
      "status_code": "800",
      "filing_date": "2010-02-24T00:00:00Z",
      "registration_date": "2011-06-07T00:00:00Z",
      "renewal_date": "0001-01-01T00:00:00Z",
      "owner_name": "TWAIN Working Group",
      "goods_services": "Software",
      "class_numbers": ["A"],
      "match_score": 1,
      "match_details": {
        "exact_match": false,
        "phonetic_match": false,
        "fuzzy_distance": 0,
        "jaro_winkler": 0,
        "prefix_match": false,
        "bleve_score": 0.2965025984223124
      },
      "tsdr_enriched": false
    }
  ],
  "total": 3,
  "limit": 1,
  "offset": 0,
  "query": "software",
  "took_ms": 1261,
  "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."
}
```

---

#### Search by Owner Name

```
GET /v1/trademark/search/owner
```

Parameters:
- q (string, required): Owner name to search for (e.g., "google")
- limit (integer, optional): Maximum results to return (default: 10)
- offset (integer, optional): Number of results to skip for pagination

Example request:
```
GET https://api.robotdomainsearch.com/v1/trademark/search/owner?q=google&limit=1
```

Example response:
```json
{
  "results": [
    {
      "serial_number": "74487400",
      "mark_text": "DOUBLECLICK",
      "status_code": "800",
      "filing_date": "1994-02-07T00:00:00Z",
      "registration_date": "1995-09-12T00:00:00Z",
      "renewal_date": "0001-01-01T00:00:00Z",
      "owner_name": "GOOGLE LLC",
      "goods_services": "advertising agency services",
      "class_numbers": ["035"],
      "match_score": 1,
      "match_details": {
        "exact_match": false,
        "phonetic_match": false,
        "fuzzy_distance": 0,
        "jaro_winkler": 0,
        "prefix_match": false,
        "bleve_score": 1.793308868266384
      },
      "tsdr_enriched": false
    }
  ],
  "total": 3,
  "limit": 1,
  "offset": 0,
  "query": "google",
  "took_ms": 110,
  "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."
}
```

---

#### Find Expiring Trademarks

```
GET /v1/trademark/search/expiring
```

Parameters:
- days (integer, required): Number of days ahead to search for expiring trademarks
- limit (integer, optional): Maximum results to return (default: 10)
- offset (integer, optional): Number of results to skip for pagination

Example request:
```
GET https://api.robotdomainsearch.com/v1/trademark/search/expiring?days=30&limit=1
```

Example response:
```json
{
  "results": [
    {
      "serial_number": "74246564",
      "mark_text": "WYNDHAM GARDEN",
      "status_code": "800",
      "filing_date": "1992-02-14T00:00:00Z",
      "registration_date": "1996-03-19T00:00:00Z",
      "renewal_date": "2026-03-19T00:00:00Z",
      "owner_name": "Wyndham Hotels and Resorts, LLC",
      "goods_services": "hotel services; namely, providing lodgings, rooms and meals",
      "class_numbers": ["042"],
      "match_score": 0.08396005257514837,
      "match_details": {
        "exact_match": false,
        "phonetic_match": false,
        "fuzzy_distance": 0,
        "jaro_winkler": 0,
        "prefix_match": false,
        "bleve_score": 0.08396005257514837
      },
      "tsdr_enriched": false
    }
  ],
  "total": 3,
  "limit": 1,
  "offset": 0,
  "query": "",
  "took_ms": 114,
  "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."
}
```

---

#### Trademark Index Status

```
GET /v1/trademark/search/status
```

No parameters required. Returns health and metadata of the trademark search index.

Example request:
```
GET https://api.robotdomainsearch.com/v1/trademark/search/status
```

Example response:
```json
{
  "available": true,
  "total_documents": 13931255,
  "index_size_bytes": 30125729415,
  "last_updated": "2026-03-16T01:51:07Z"
}
```

---

#### Trademark Response Fields

Top-level fields:
- `results` (array): Array of trademark result objects
- `total` (integer): Total number of matching results
- `limit` (integer): Maximum results returned per request
- `offset` (integer): Number of results skipped (for pagination)
- `query` (string): The search query that was executed
- `took_ms` (integer): Query execution time in milliseconds
- `index_info` (object): Information about the trademark index
- `disclaimer` (string): Legal disclaimer about data source

Result fields:
- `serial_number` (string): USPTO serial number for the trademark application
- `mark_text` (string): The registered trademark text
- `status_code` (string): USPTO status code (602=abandoned, 700=registered active, 710=cancelled, 800=registered and renewed, 900=expired)
- `filing_date` (string): ISO 8601 date when the application was filed
- `registration_date` (string): ISO 8601 date when the trademark was registered
- `renewal_date` (string): ISO 8601 date of next renewal (`0001-01-01T00:00:00Z` if not applicable)
- `owner_name` (string): Name of the trademark owner
- `goods_services` (string): Description of goods/services covered by the trademark
- `class_numbers` (array): Nice classification numbers for the trademark
- `match_score` (number): Overall relevance score (0.0–1.0)
- `match_details` (object): Detailed matching information
- `tsdr_enriched` (boolean): Whether the result has been enriched with TSDR data

Match details fields:
- `exact_match` (boolean): True if query exactly matches the mark text
- `phonetic_match` (boolean): True if query phonetically matches the mark
- `fuzzy_distance` (integer): Edit distance between query and mark (0 = exact)
- `jaro_winkler` (number): Jaro-Winkler similarity score (0.0–1.0)
- `prefix_match` (boolean): True if the mark starts with the query
- `phonetic_codes` (string): Phonetic encoding of the query
- `matched_codes` (string): Phonetic encoding of the matched mark
- `bleve_score` (number): Raw search engine relevance score

Index status fields:
- `available` (boolean): True if the trademark index is operational
- `total_documents` (integer): Total number of trademarks in the index
- `index_size_bytes` (integer): Size of the index in bytes
- `last_updated` (string): ISO 8601 date when the index was last updated

Errors:
| Code | Error | Description |
|------|-------|-------------|
| 400 | missing_parameter | Required parameter q or days is missing |
| 405 | method_not_allowed | Only GET method is allowed |
| 429 | rate_limited | Rate limit exceeded |
| 500 | internal_error | An unexpected error occurred |
| 503 | service_unavailable | Trademark search index is not available |

---

## MCP Tool → API Mapping

| MCP Tool | API Endpoint | Paid |
|----------|--------------|------|
| check_domain | GET /v1/check | No |
| whois_lookup | GET /v1/whois | No |
| domain_intel | GET /v1/intel | $0.05 |
| domain_valuation | GET /v1/valuation/{domain} | $0.02/$0.08 |
| list_tlds | GET /v1/tlds | No |
| get_registration_link | GET /v1/register | No |
| search_auctions | GET /v1/auctions | No |
| ens_check | GET /v1/ens/check | No |
| ens_metadata | GET /v1/ens/metadata | No |
| trademark_search | GET /v1/trademark/search | No |
| trademark_search_description | GET /v1/trademark/search/description | No |
| trademark_search_owner | GET /v1/trademark/search/owner | No |
| trademark_search_expiring | GET /v1/trademark/search/expiring | No |

---

## OpenAPI Specification

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

## Links

- Website: https://robotdomainsearch.com
- API Docs: https://robotdomainsearch.com/docs/api/
- Payments: https://robotdomainsearch.com/docs/payments/
- MCP Server: https://robotdomainsearch.com/mcp/
- GitHub: https://github.com/robotdomainsearch
- npm: https://www.npmjs.com/package/@robotdomainsearch/mcp