---
title: Find Domain — Developer Portal
description: Quickstart, endpoint reference, authentication, sandbox, rate limits, versioning, and error model for the Find Domain API.
canonical: https://finddomain.io/developers
last-updated: 2026-08-27
---

# Developer Portal

Pay-per-query domain research over plain HTTP. No signup precedes the first request.

## Quickstart

Free sandbox call, no payment or key:

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

Paid queries use the x402 payment protocol (USDC on Base). SDKs:
`pip install x402` (Python), `npm install @x402/fetch @x402/evm viem` (Node.js).
The SDK handles the 402 → sign → retry flow automatically.

## 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 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.json](https://finddomain.io/openapi.json) ·
[skill.md](https://finddomain.io/skill.md) · [pricing.md](https://finddomain.io/pricing.md)

## Authentication — no API keys

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`). Sign a gasless EIP-3009 USDC authorization and
retry. Details: [auth.md](https://finddomain.io/auth.md).

## Sandbox

`GET /demo?query=TERM` is the sandbox: the real suggestion pipeline, free,
limited to 5 alphabetized results and 3 queries/day per IP. It exercises the
same validation and response shape as the paid `/suggest` endpoint.

## Rate limits

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

## 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 `Deprecation` and `Sunset`
headers at least 90 days before removal. Additive changes are not versioned.

## Errors

Every error response is JSON: `{"error": "message"}` plus an optional `"help"`
field with a corrective hint. Retried Scout 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 [openapi.json](https://finddomain.io/openapi.json).

## Agent integration

- [skill.md](https://finddomain.io/skill.md) — agent skill with full endpoint and payment documentation
- `https://finddomain.io/mcp` — MCP server (Streamable HTTP)
- [llms.txt](https://finddomain.io/llms.txt) — LLM-friendly overview with when-to-use guidance
- [ai-catalog.json](https://finddomain.io/.well-known/ai-catalog.json) — ARD capability manifest