---
name: find-domain
version: 1.0.0
description: Domain name suggestions and availability checks powered by Fastly's Domain Research API. Use when searching for available domain names, checking if a specific domain is taken, or brainstorming domain ideas for a project. Costs $0.002–$0.010 USDC per query via x402 — no API key needed.
homepage: https://finddomain.io
metadata: {"openclaw":{"emoji":"🌐","category":"domain-research","api_base":"https://finddomain.io","payment":"x402","network":"eip155:8453"}}
---

# Find Domain

Domain name suggestions and availability checks. **Base URL:** `https://finddomain.io`

---

## Endpoints

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /suggest?query=TERM` | $0.002 | Algorithmic domain name suggestions (stemming, IDN normalization, alternatives) |
| `GET /status?domain=DOMAIN` | $0.010 | Precise registry-level availability check — definitive answer |
| `GET /status?domain=DOMAIN&scope=estimate` | $0.003 | Estimated availability via DNS — fast, no registry lookup |
| `GET /demo?query=TERM` | Free | Limited demo: 5 alphabetized suggestions, 3 queries/day per IP |

---

## Parameters

**`/suggest`:**
- `query` — search term(s). **Required.** (e.g. `tea`, `my startup name`)
- `defaults` — comma-separated default zones to include (e.g. `com,io,co`)
- `keywords` — comma-separated keywords for seeding results (e.g. `food,kitchen`)
- `location` — two-letter country code for geo-relevant zones (e.g. `de`)
- `vendor` — registrar domain for filtering by supported zones (e.g. `dnsimple.com`)

**`/status`:**
- `domain` — fully qualified domain to check. **Required.** (e.g. `tea.com`, `example.io`)
- `scope=estimate` — use DNS-based estimation instead of registry lookup

**`/demo`:**
- `query` — search term(s). **Required.** Same as `/suggest` but free, rate-limited, and truncated.

---

## Example Responses

### `GET /suggest?query=tea`

```json
{
  "results": [
    { "domain": "tea.com", "subdomain": "tea.", "zone": "com" },
    { "domain": "tea.house", "subdomain": "tea.", "zone": "house" },
    { "domain": "tea.cafe", "subdomain": "tea.", "zone": "cafe" },
    { "domain": "tea.net", "subdomain": "tea.", "zone": "net" },
    { "domain": "tea.org", "subdomain": "tea.", "zone": "org" }
  ]
}
```

> Suggestions do **not** include availability status. Use `/status` to check if a specific domain is available.

### `GET /status?domain=acmecoffee.shop`

```json
{
  "domain": "acmecoffee.shop",
  "zone": "shop",
  "status": "undelegated inactive",
  "tags": "generic"
}
```

### `GET /status?domain=tea.com&scope=estimate`

```json
{
  "domain": "tea.com",
  "zone": "com",
  "status": "active",
  "tags": "generic",
  "scope": "estimate"
}
```

**Understanding `status` values:** The `status` field is a space-delimited list, rightmost value is most important.
- `inactive` — available for registration
- `active` — registered (possibly available via aftermarket)
- `undelegated` — not present in DNS
- `premium` — premium-priced by the registry

See the [Fastly Domain Research API docs](https://www.fastly.com/documentation/reference/api/domain-management/domain-research/) for the full list of status values.

---

## Error Handling

| Status | Meaning | What to do |
|--------|---------|------------|
| `400` | Validation error | Check the `"error"` and `"help"` fields in the response for details (missing/invalid parameters) |
| `402` (no sig) | Payment required | Send `PAYMENT-REQUIRED` header to client wallet to sign |
| `402` (bad sig) | Payment invalid | Signature expired, wrong amount, or insufficient balance — re-sign |
| `404` | Unknown endpoint | Check endpoint path: only `/suggest`, `/status`, `/demo`, `/skill.md`, `/` are valid |
| `405` | Method not allowed | Only `GET` requests are accepted |
| `429` | Rate limited | Demo endpoint only — 3 queries/day per IP. Use `/suggest` with payment for unlimited access |
| `502` | Upstream error | Fastly API or facilitator is temporarily unavailable — retry with backoff |

A `402` with an error message in the decoded `payment-required` header indicates a specific
rejection reason (e.g. `"payment invalid: insufficient balance"`).

---

## Rate Limits

Paid endpoints (`/suggest`, `/status`) have no rate limits. Each request is independently priced
and settled. Fastly's infrastructure handles concurrency at the edge.

The free `/demo` endpoint is limited to 3 queries per day per IP address.

---

## Using @x402/fetch (Recommended — Node.js / TypeScript)

`@x402/fetch` wraps the standard `fetch` API and handles the x402 payment flow automatically.

```bash
npm install @x402/fetch @x402/evm viem
```

```js
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.PRIVATE_KEY),
});
const fetch = wrapFetchWithPayment(globalThis.fetch, client);

// Domain suggestions (with optional keyword seeding)
const res = await fetch("https://finddomain.io/suggest?query=tea&keywords=organic,herbal&defaults=com,io");
const data = await res.json();
console.log(data);

// Check precise availability
const status = await fetch("https://finddomain.io/status?domain=tea.com");
console.log(await status.json());

// Check estimated availability (cheaper)
const estimate = await fetch("https://finddomain.io/status?domain=tea.io&scope=estimate");
console.log(await estimate.json());
```

---

## Using x402 Python SDK

```bash
pip install x402
```

```python
import os
from x402.client import Client
from eth_account import Account

account = Account.from_key(os.environ["PRIVATE_KEY"])
client = Client(account)

# Domain suggestions
suggestions = client.get("https://finddomain.io/suggest", params={"query": "tea"})
print(suggestions.json())

# Precise availability
status = client.get("https://finddomain.io/status", params={"domain": "tea.com"})
print(status.json())
```

---

## How to Make a Paid Request (x402 Flow)

Every request follows the same two-step pattern:

### Step 1: Make the initial request

```bash
curl -si https://finddomain.io/suggest?query=tea
```

Response:
```
HTTP/2 402 Payment Required
payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIi...
content-type: application/json
```

Decode the `payment-required` header (base64 JSON) to see:
```json
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://finddomain.io/suggest?query=tea",
    "description": "Domain name suggestions",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "2000",
    "payTo": "0xe6C6160749382f4d4d7285465C53d47Fa269a872",
    "maxTimeoutSeconds": 60,
    "extra": {
      "name": "USD Coin",
      "version": "2",
      "assetTransferMethod": "eip3009"
    }
  }]
}
```

`"amount": "2000"` = 2,000 atomic USDC units = **$0.002**.

### Step 2: Sign and retry

Use an x402-compatible client to sign the payment and retry. The client handles signing
automatically — you just call the URL once and it manages the 402 → sign → retry cycle.

On success you receive:
```
HTTP/2 200 OK
payment-response: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4Li4uIn0=
content-type: application/json
```

The `payment-response` header (base64 JSON) contains the settlement transaction hash:
```json
{
  "success": true,
  "transaction": "0xabc123...",
  "network": "eip155:8453",
  "payer": "0xYOUR_WALLET"
}
```

---

## Manual curl Flow (Debugging)

When you need to inspect the raw payment headers:

```bash
# 1. Get the 402 and decode the payment requirements
PAYMENT_REQUIRED=$(curl -si https://finddomain.io/suggest?query=tea \
  | grep -i "^payment-required:" \
  | awk '{print $2}' \
  | tr -d '\r')

echo "$PAYMENT_REQUIRED" | base64 -d | python3 -m json.tool

# 2. Sign a payment using @x402/fetch or the x402 CLI, then retry:
curl -s https://finddomain.io/suggest?query=tea \
  -H "payment-signature: BASE64_SIGNED_PAYLOAD" \
  | python3 -m json.tool
```

For manual signing, refer to the [x402 protocol spec](https://x402.org) and EIP-3009.

---

## What is x402?

x402 is an open HTTP payment protocol. When a server returns `402 Payment Required`, it
includes a `PAYMENT-REQUIRED` header with a machine-readable price and destination address.
The client signs a USDC authorization (EIP-3009, gasless on Base) and retries. Settlement
happens on-chain; the payment-response header confirms the transaction hash.

→ [x402.org](https://x402.org) · [GitHub](https://github.com/coinbase/x402)

---

## No Registration Required

There is no API key. Payment **is** the authentication.

You need:
- A wallet with **USDC on Base mainnet** (`eip155:8453`)
- An x402-compatible client (@x402/fetch, x402 Python SDK, or manual signing)

If you don't have Base USDC yet: [Coinbase onramp](https://www.coinbase.com/price/usd-coin)

The minimum balance required per session is typically $0.002–$0.010 depending on the endpoint.

---

## Install Locally

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://finddomain.io/skill.md` |

```bash
# OpenClaw
mkdir -p ~/.openclaw/workspace/skills/find-domain
curl -s https://finddomain.io/skill.md > ~/.openclaw/workspace/skills/find-domain/SKILL.md

# Claude Code
mkdir -p ~/.claude/skills/find-domain
curl -s https://finddomain.io/skill.md > ~/.claude/skills/find-domain/SKILL.md
```

**Or fetch the URL at runtime** — no local install needed.