# TLD Bench

> Domain prices for every TLD at every registrar. Registration, renewal, transfer and restore prices at the top registrars,
> refreshed daily, with N-year totals, price history and availability checks. A keyless REST
> API and a remote MCP server for agents.

TLD Bench is an independent price index, **not a registrar**: it sells nothing, ranks only by
price and the published method (no sponsored placement), and its outbound links are plain
links with no affiliate code. Prices are each registrar's own list prices (register, renew,
transfer, restore), collected daily from its price list or API, with N-year totals computed
the same way everywhere (minimum term, then regular renewals). Premium names are excluded.

Everything on the site is in the REST API and the MCP server, with the same numbers.

## Connect

- MCP (Streamable HTTP, no key): `https://tldbench.com/mcp`. Claude Code:
  `claude mcp add --transport http tldbench https://tldbench.com/mcp`. Other clients: https://tldbench.com/agents
- REST: [OpenAPI 3.1](https://tldbench.com/openapi.json). Each tool's operationId in the OpenAPI document
  is the tool's name; POST bodies are the tools' arguments.
- [Full manual](https://tldbench.com/llms-full.txt): every tool's parameters and every route.

## Which tool answers which question

- `compare_tld_prices` (`GET /v1/tlds/{tld}/prices`): Use this when the user asks what an extension costs or where it is cheapest. Returns every registrar's register, renew, transfer and restore prices for one TLD, ranked by the N-year cost of ownership (default 3 years), with each price's source and date.
- `cheapest_registrar` (`GET /v1/cheapest`): Use this when the user wants the single best place to buy (or transfer) one or more extensions for N years. Ranks by the total cost of ownership, not the first-year promotion; returns the winner with a year-by-year breakdown, three runners-up and caveats. Up to 20 extensions in one call.
- `total_cost_of_ownership` (`POST /v1/cost`): Use this when the user compares the long-run cost of several names or extensions, at one registrar or the cheapest. Applies minimum terms and regular renewals; with transfer_after_year it also finds the cheapest registrar to move to later. Up to 20 domains or extensions in one call.
- `check_availability` (`POST /v1/availability`): Use this when the user asks whether specific domain names are free. Checks the registry (RDAP, WHOIS for some ccTLDs) after a DNS pre-check, with an honest unknown, and adds the cheapest registrar's price to own each free name. Up to 50 names in one call.
- `search_name_across_tlds` (`POST /v1/search`): Use this when the user has a name and wants to know which extensions are free and what each costs to own. Checks one label across up to 50 extensions (or a preset: popular, tech, cheap, country:<cc>) and sorts the free ones by total cost.
- `suggest_names` (`POST /v1/suggest`): Use this when the user needs name ideas. Pass `candidates` from your own brainstorm and we check and price them; with only `keywords` we add simple prefixes, suffixes, TLD hacks and combinations. Returns only names that are available or unknown, cheapest first.
- `get_registrar` (`GET /v1/registrars/{id}`): Use this when the user asks about a registrar: its country, group, size (gTLD domains under management), how many extensions it sells, and how fresh our prices for it are. Accepts our id, its name or an IANA id.
- `price_history` (`GET /v1/tlds/{tld}/history`): Use this when the user asks how an extension's prices have moved or whether a rise is coming. Returns each registrar's price periods (changes only) and the registry's announced wholesale changes.
- `list_coupons` (`GET /v1/coupons`): Use this when the user asks for promo codes, coupons, deals or first-year discounts. Returns coupon codes as each registrar's own API or promotions page lists them (code, operation, extensions, discount, limits, end date, last seen at the source, an example price with the code), and running promotional prices anyone gets without a code. Codes are seen at the source, not tested at checkout; quote the list price and renewal too.
- `get_tld` (`GET /v1/tlds/{tld}`): Use this when the user asks what an extension is, who runs it, or whether it fits: type (generic or country code), registry, brand TLD or not, DNSSEC, RDAP and WHOIS servers, minimum term, second levels, registry fees, and its price summary.

## Worked examples

**"What does .io cost, and where is it cheapest?"**

    compare_tld_prices {"tld": "io", "years": 3}
    GET https://tldbench.com/v1/tlds/io/prices?years=3

Answer with the top three by `totals.total` (the 3-year cost), each with its renewal price.
A registrar whose year 1 is a promotion (`register.promo: true`) is cheap only once: say so.

**"Is acmeforge free? Check .io and .ai too."**

    check_availability {"domains": ["acmeforge.com", "acmeforge.io", "acmeforge.ai"]}
    POST https://tldbench.com/v1/availability  {"domains": [...]}

One batch, not three calls. Sort the free ones by `cheapest.total`, not by first year: .ai
bills two years up front, so its `first_payment` is twice the yearly price. `unknown` means no
registry answered: never call it free. `premium_unknown: true` (.ai, .io and most new gTLDs):
the registry may price the name as premium; tell the user to confirm the price at checkout.

**"I have a name. Which extensions are free and what do they cost?"**

    search_name_across_tlds {"name": "acmeforge", "preset": "popular"}

Presets: `popular`, `tech`, `cheap` (the 15 cheapest to own), `country:de`. Report the free
ones with their 3-year total and stop; the taken ones are worth a count, not a row each.

**"Give me name ideas for a coffee roastery."**

Brainstorm the names yourself (TLD Bench makes no LLM calls), then:

    suggest_names {"candidates": ["beanhaus", "roastly", "brewbench"], "tlds": ["com", "coffee", "cafe"]}

It returns only names that are free or unknown, cheapest to own first. With `keywords` instead
of `candidates` it tries simple variants (prefixes, suffixes, pairs, TLD hacks).

**"Which registrar is cheapest for .com over 5 years? Should I move later?"**

    cheapest_registrar {"tlds": ["com"], "years": 5}
    total_cost_of_ownership {"tlds": ["com"], "years": 5, "transfer_after_year": 1}

The second gives `switch`: register where year 1 is cheapest, transfer to the cheapest renewing
registrar, and the saving.

**"Has .com got more expensive?"**

    price_history {"tld": "com", "operation": "renew"}

`registry_events` holds the registry's wholesale changes (Verisign's .com fee rose on
2026-11-01); `series` each registrar's price periods (changes only, native currency beside).

## How to present answers

- **Renewal is the real price.** Lead with the renewal and the N-year total
  (`totals.total`, `first_payment`); a first-year promotion renews at `regular`.
- **Minimum terms.** `min_years` (2 for .ai): the first bill covers that many years.
- **Per year, with a term.** Every price is per year, for every operation; `term_years`
  says how many years the operation buys at once (a .ai transfer adding 2 years costs
  `price` x 2). `scheduled` is a regular price change the registrar has announced.
- **Limited promotions are not ranked.** `promo_limited: true` (one per customer, first-time
  customers only, "up to 5 domains"): shown with its `promo_conditions`, but totals, sorting,
  cheapest and headlines price year 1 at the regular price. `include_limited_promos=true`
  counts them. `totals.estimated: true`: a year whose regular price is unknown was priced at
  the regular renewal; say "about". `promo_inferred: true`: the registrar marks no
  promotion, but year 1 is below the renewal, so we treat it as a first-year price.
- **Renewal promotions never count.** Totals use the regular renewal every year, even while a
  registrar discounts renewals (that discount is shown as `renew.promo`).
- **Reseller tiers and notes.** `registrar.pricing_tier: "reseller"` (eNom) means the prices
  need a reseller account: left out of rankings unless `include_resellers=true`. Quote a
  registrar's `note` with its prices (NameSilo's free discount program).
- **`unknown` is not available.** And `null` is unknown, never zero or free.
- **Premium names are excluded.** Our prices are standard prices; `premium_unknown` warns
  when the registry may charge more for a specific name.
- **Cite.** Every price has its registrar, `source.url`, and `observed_at` (the last time the
  source confirmed it); `stale: true` means not confirmed recently. Give the date.
- **Link.** Each result has `url`, the tldbench.com page with the full comparison.
- **Escape `$`.** Write "USD 12.99" or `\$12.99`: two bare dollar signs on one line are read
  as math by many chat renderers, and the text between them disappears.
- **Currency.** Pass `currency` (ISO 4217); conversions use the ECB's daily reference rate,
  disclosed in `fx`, and each converted price keeps its `native` amount.

## Limits, errors, caching

- No key, no account. Per IP: **120 requests a minute** (REST and MCP
  together) and **60 new availability lookups a minute** (a name answered from our
  cache costs nothing; one checked in the last few minutes is cached). Over a limit: HTTP
  `429` with `Retry-After` (MCP tools: `isError` with the wait).
- Batches: up to 50 domains and 20 extensions per call; 100 candidates for suggest_names.
  Parallel calls are fine.
- Availability answers are cached: available 10 minutes, registered 24 hours (1 hour near
  expiry or in redemption); `unknown` is not cached, so asking again retries. `cached` and `cache_age_s` say how old an answer is.
- We query registries politely: at most ~10 RDAP lookups a minute and 2 at once per RDAP
  host, a circuit breaker on 429s, WHOIS only for single checks of ccTLDs without RDAP.
  Registry lookups use the User-Agent `TLDBench-availability/1.0 (+https://tldbench.com/agents)`.
- Price data changes once a day; GET responses are cacheable for 5 minutes.
- Errors are JSON: `{"error": {"code", "message", "hint"}}`, codes `bad_request`,
  `not_found`, `rate_limited`, `internal_error`.
- Every API response links its description: `Link: <https://tldbench.com/openapi.json>; rel="describedby"`.

## Optional

- [Sources and freshness](https://tldbench.com/v1/sources): where each registrar's prices come from, when
  they were last read, and anything held for confirmation
- [Every extension](https://tldbench.com/v1/tlds) and [every registrar](https://tldbench.com/v1/registrars)
- [Price changes](https://tldbench.com/v1/changes), [stats](https://tldbench.com/v1/stats)
- [MCP server card](https://tldbench.com/.well-known/mcp/server-card.json)
- Every page of the site as markdown: add `.md` (https://tldbench.com/tld/io.md)