---
title: Register a domain with an API: search, quote, checkout and order tracking (curl examples)
description: How developers search domains, hand over a buy link or create a quote, start a checkout and track the order with the Nymwell REST API, with curl examples to copy.
updated: 2026-10-27
---

# Register a domain with an API

The Nymwell REST API searches domains, returns live prices, creates quotes and checkouts, and tracks orders. Searching needs no key; quoting or ordering on someone's behalf needs an agent key (or use MCP sign-in instead). An agent key pays with the person's saved card, within the spending limits; with no card or over a limit, the order returns a checkout link for the person.

Base address: `https://nymwell.com/api/v1`. The full contract is the [OpenAPI document](https://nymwell.com/openapi.json).

## Step 1: search (no key)

```bash
curl "https://nymwell.com/api/v1/domains/search?q=yourbrand&tlds=com,dev,app"
```

Every name has `available`. One you can register comes with `tier`, the first-term price, the renewal price and a `buy_url`; one you can't comes with a `reason` such as `domain_unavailable` or `extension_not_supported`.

```json
{
  "domain": "yourbrand.dev",
  "available": true,
  "tier": "standard",
  "price_display": "US$19.84",
  "renewal_display": "US$30.21",
  "buy_url": "https://nymwell.com/buy?domain=yourbrand.dev"
}
```

Registrar-backed checks (`search`, `suggest`) allow, per minute: 30 with no key, 60 for an agent signed with Web Bot Auth, 120 with an agent key; past that the answer is 429 with `retry_after_seconds`.

To screen many names at once, call `POST /api/v1/domains/lookup` first (up to 500 names, DNS and RDAP only, no registrar call), then confirm the names with no record through `search`. A lookup result is screening, not proof a name can be registered.

**In a terminal** (Claude Code, Codex or a shell script) you can skip curl and use the Nymwell command line, with nothing to install:

```bash
npx nymwell lookup yourbrand --tlds all   # screen many names at once (public records only)
npx nymwell check yourbrand.dev           # the registrar's answer, with the exact price
```

With `NYMWELL_KEY` set to an agent key, `quote`, `buy` and `order` quote and place orders; add `--json` for the raw response. The package is on [npm](https://www.npmjs.com/package/nymwell).

## Step 2a: the simplest path, hand over the buy link

If your product only needs the person to own the domain, give them `buy_url`. They sign in with Google, check the price and pay, and the domain is registered to their account. No key involved.

## Step 2b: quote and order on the person's behalf

To create orders in your own flow, the person creates an agent key on Nymwell's AI Agents page with `quotes:create` and `orders:create`. The key is shown once; keep it in a server environment variable, never in code.

**Quote (the price is held for 40 minutes):**

```bash
curl -X POST https://nymwell.com/api/v1/quotes \
  -H "X-Nymwell-Key: $NYMWELL_KEY" \
  -H "content-type: application/json" \
  -d '{"domain":"yourbrand.dev","action":"register","years":1,"currency":"USD"}'
```

**Order:**

```bash
curl -X POST https://nymwell.com/api/v1/orders \
  -H "X-Nymwell-Key: $NYMWELL_KEY" \
  -H "content-type: application/json" \
  -d '{"quote_id":"quote_..."}'
```

If the workspace has a saved card and the amount is within the agent spending limit (by default US$100 per order and US$500 per 30 days; an owner changes it in Settings), the order is paid with that card and `workflow.state` is `in_progress`. With no card, over a limit, or when you send `"pay_with": "checkout"`, the answer carries a `checkout_url` and `workflow.state` is `action_required`: give the link to the person.

**Track the order:**

```bash
curl -H "X-Nymwell-Key: $NYMWELL_KEY" "https://nymwell.com/api/v1/orders?id=ord_..."
```

Read `workflow.state`: `in_progress` or `blocked` means check again later; `succeeded` means registered; `failed` carries `workflow.error` with the reason.

Before the first purchase, the workspace needs a registrant; otherwise the answer is `409 registrant_required`. The person adds it in the console, or a key with `account:manage` sends it to `POST /api/v1/registrant`.

## Step 3: DNS

You can pass a DNS preset with the order (Vercel, Netlify, GitHub Pages, Cloudflare Pages, Agent Lab Deploy, Google Workspace); it is created with the registration after payment, because paying is the person's approval. DNS changes after that go through `POST /api/v1/dns/change-sets`: an agent key's changes apply directly by default, or return a `workflow` waiting for approval if the workspace's Settings ask for it.

## Common errors

| Error | What to do |
| --- | --- |
| `authentication_required` | The endpoint needs an agent key, or use `buy_url` |
| `insufficient_scope` | The key lacks that scope; create a new one with it |
| `quote_expired` | The quote is older than 40 minutes; quote again |
| `registrant_required` | The person adds the registrant in the console, or send it to `POST /api/v1/registrant` |
| `agent_spend_limit` | Over the agent spending limit; nothing was charged. Give the person the `checkout_url`, or ask an owner to raise the limit |
| `rate_limited` | Wait `retry_after_seconds` and try again |

Every status and error code is on [statuses and errors](https://nymwell.com/en/docs/reference/).

## Questions

**Does the API cost anything?**
No. Only the domain itself is paid per registration, at the same price as the website.

**Can I buy fully automatically, without the person?**
Yes, within limits: only the person can add the card, and an agent can only charge it within the per-order and 30-day spending limits. With the limit at 0, every order goes back to a checkout the person pays.

**Is there a sandbox?**
Not a public one. Build against the keyless search and `buy_url` first, then verify the purchase path with one real, low-priced domain.

**Can AI agents use this?**
Yes, and [MCP](https://nymwell.com/en/docs/mcp/) is the better fit: the agent signs in with Google once and never handles a key.

## Related

- [Domain registration API overview](https://nymwell.com/en/developers/api/)
- [REST API reference](https://nymwell.com/en/docs/api/)
- [Let AI buy a domain for you](https://nymwell.com/en/guides/buy-a-domain-with-ai/)
- [Domain registrar API vs MCP](https://nymwell.com/en/guides/domain-registrar-api-vs-mcp/)