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.
Step 1: search (no key)
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.
{
"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.
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):
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:
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:
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_ | The endpoint needs an agent key, or use buy_ |
insufficient_ | The key lacks that scope; create a new one with it |
quote_ | The quote is older than 40 minutes; quote again |
registrant_ | The person adds the registrant in the console, or send it to POST /api/v1/registrant |
agent_ | Over the agent spending limit; nothing was charged. Give the person the checkout_, or ask an owner to raise the limit |
rate_ | Wait retry_ and try again |
Every status and error code is on statuses and errors.
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 is the better fit: the agent signs in with Google once and never handles a key.