Developer Portal

Everything needed to integrate the Find Domain API: pay-per-query domain research over plain HTTP. No signup precedes the first request.

Quickstart

Try the free sandbox endpoint — no payment, no key:

curl "https://finddomain.io/demo?query=artisan+tea"

Paid queries use the x402 payment protocol. With the Python SDK:

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

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

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

The x402 Python SDK handles the 402 → sign → retry flow. Install: pip install x402. Node.js: npm install @x402/fetch @x402/evm viem — full examples on the homepage.

Endpoints

Endpoint	Price	Description
`GET /suggest?query=TERM`	$0.005	Domain name suggestions
`GET /status?domain=DOMAIN`	$0.020	Registry-precise availability check
`GET /status?domain=DOMAIN&scope=estimate`	$0.005	DNS-based availability estimate
`POST /scout`	$0.15 / $0.50	Research job: ranked, evidence-backed shortlist; amount paid selects the tier
`GET /scout/JOB_ID`	Free	Poll a Scout job
`GET /demo?query=TERM`	Free	Sandbox: 5 results, 3 queries/day per IP

Full parameter reference: OpenAPI 3.1 spec · agent skill file · pricing

Authentication — no API keys

There are no API keys, accounts, or OAuth grants. Payment is authentication: an unpaid call to a paid endpoint returns 402 Payment Required with machine-readable x402 payment requirements (USDC on Base, eip155:8453). The client signs a gasless EIP-3009 USDC authorization and retries. x402 SDKs for Node.js and Python handle the flow automatically. Details: auth.md.

Sandbox

GET /demo?query=TERM is the sandbox: the real suggestion pipeline, free, limited to 5 alphabetized results and 3 queries per day per IP. It exercises the same request validation and response shape as the paid /suggest endpoint, so an integration tested against /demo works unchanged against /suggest plus the x402 payment flow.

Rate limits

Paid endpoints have no rate limits. The free /demo endpoint allows 3 queries per day per IP and reports its state with RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset response headers; an exhausted limit returns 429 with a Retry-After header.

Versioning & deprecation

The current API surface is version 1, reported by the X-Api-Version response header on every response. Breaking changes ship as a new version at a new path prefix (/v2/...); the previous version then serves a Deprecation header and a Sunset header at least 90 days before removal. Additive changes (new fields, new endpoints) are not versioned.

Errors

Every error response is JSON with a machine-readable shape: {"error": "message"}, plus an optional "help" field with a corrective hint. Retried Scout job submissions can carry an Idempotency-Key header so a network-level retry returns the original job instead of starting a second one. Error schemas are declared per status code in the OpenAPI spec.

Agent integration

skill.md — Claude Code / agent skill with full endpoint and payment documentation
https://finddomain.io/mcp — MCP server (Streamable HTTP), tools for every endpoint
llms.txt — LLM-friendly site overview with when-to-use guidance
ai-catalog.json — ARD capability manifest