---
title: 用 API 註冊網域：查詢、報價、結帳與追蹤訂單（curl 範例）
description: 開發者用 Nymwell REST API 查網域、取得購買連結或報價、下單付款並追蹤訂單的完整步驟，附可直接複製的 curl 範例。
updated: 2026-10-27
---

# 用 API 註冊網域

Nymwell 的 REST API 可以查網域、取得即時價格、報價、建立結帳並追蹤訂單。查詢不需要 key；要代表使用者報價或下單，需要 agent key（或改用 MCP 登入）。agent key 下單時，會用使用者存好的卡在花費上限內付款；沒存卡或超過上限，就回傳結帳連結給使用者。

基本位址：`https://nymwell.com/api/v1`。完整規格在 [OpenAPI](https://nymwell.com/openapi.json)。

## 步驟一：查詢（免 key）

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

每個網域會回傳 `available`。可以註冊的會附 `tier`、首期價格、續約價格與 `buy_url`；不能註冊的會附 `reason`（例如 `domain_unavailable`、`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"
}
```

向註冊商確認的查詢（`search`、`suggest`）每分鐘：免 key 30 次、以 Web Bot Auth 簽章的 agent 60 次、帶 agent key 120 次；超過會回 429 與 `retry_after_seconds`。

要一次篩很多名稱，先用 `POST /api/v1/domains/lookup`（最多 500 個，只讀 DNS 與 RDAP、不打註冊商），再把看起來沒人用的名稱交給 `search` 確認。`lookup` 的結果只是初篩，不代表可以註冊。

**在終端機裡**（Claude Code、Codex 或 shell 腳本）也可以不寫 curl，直接用 Nymwell 的命令列工具，不用安裝：

```bash
npx nymwell lookup yourbrand --tlds all   # 一次快查很多名稱（只看公開紀錄）
npx nymwell check yourbrand.dev           # 向註冊商確認，附確切價格
```

設定 `NYMWELL_KEY`（agent key）後，也能用 `quote`、`buy`、`order` 報價與下單；加 `--json` 輸出原始回應。套件在 [npm](https://www.npmjs.com/package/nymwell)。

## 步驟二之一：最簡單，把購買連結交給使用者

如果你的產品只需要讓使用者買下網域，直接把 `buy_url` 交給他。他用 Google 登入、確認價格、付款，網域就會註冊到他的帳號下。這條路完全不需要 key。

## 步驟二之二：代表使用者報價與下單

需要在你的流程裡建立訂單時，使用者要先在 Nymwell 的「AI Agents」頁建立 agent key，並勾選 `quotes:create` 與 `orders:create`。key 只會顯示一次，請放在伺服器的環境變數，不要寫進程式碼。

**報價（價格鎖定 40 分鐘）：**

```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"}'
```

**建立訂單：**

```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_..."}'
```

工作空間存了卡、金額在 Agent 花費上限內（預設每筆 US$100、每 30 天 US$500，擁有者可在後台「設定」調整）時，訂單直接用那張卡付款，`workflow.state` 是 `in_progress`。沒存卡、超過上限，或你在請求帶 `"pay_with": "checkout"` 時，回應會附 `checkout_url`，`workflow.state` 是 `action_required`，請把連結交給使用者付款。

**追蹤訂單：**

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

看 `workflow.state`：`in_progress` 或 `blocked` 就稍後再查；`succeeded` 代表註冊完成；`failed` 會附 `workflow.error` 說明原因。

第一次購買前，工作空間要先有網域登記人，否則會回 `409 registrant_required`。請使用者到後台填寫，或用有 `account:manage` 權限的 key 呼叫 `POST /api/v1/registrant` 代填。

## 步驟三：設定 DNS

下單時可以帶入 DNS 預設（Vercel、Netlify、GitHub Pages、Cloudflare Pages、Agent Lab Deploy、Google Workspace），付款後會隨註冊自動建立，因為付款就是使用者的核准。註冊之後再改 DNS，用 `POST /api/v1/dns/change-sets`：agent key 的變更預設直接套用；工作空間若在「設定」選擇 Agent 變更要核准，會回傳等待核准的 `workflow`。

## 常見錯誤

| 錯誤 | 怎麼處理 |
| --- | --- |
| `authentication_required` | 這個端點需要 agent key，或改用 `buy_url` |
| `insufficient_scope` | key 缺少權限，請重新建立並勾選需要的權限 |
| `quote_expired` | 報價超過 40 分鐘，重新報價 |
| `registrant_required` | 請使用者在後台填寫網域登記人，或用 `POST /api/v1/registrant` 代填 |
| `agent_spend_limit` | 超過 Agent 花費上限，沒有扣款；把 `checkout_url` 交給使用者，或請擁有者調整上限 |
| `rate_limited` | 等 `retry_after_seconds` 秒後再試 |

所有狀態與錯誤碼在[狀態與錯誤碼](https://nymwell.com/zh-tw/docs/reference/)。

## 常見問題

**使用 API 要付費嗎？**
不用。只有網域本身依註冊逐筆付費，價格與網站相同。

**可以完全不經使用者，自動購買嗎？**
可以，在限制內：卡片必須由使用者本人在後台新增，agent 只能在每筆與每 30 天的花費上限內扣款。上限設為 0 時，每一筆都會回到結帳頁由使用者付款。

**有沙盒可以測試嗎？**
目前沒有公開的沙盒。建議先用免 key 的查詢與 `buy_url` 串接，再用一筆真實的低價網域驗證購買流程。

**AI Agent 也能用嗎？**
可以，而且更推薦用 [MCP](https://nymwell.com/zh-tw/docs/mcp/)：Agent 用 Google 登入一次即可，不需要處理 key。

## 相關

- [網域註冊 API 說明](https://nymwell.com/zh-tw/developers/api/)
- [REST API 文件](https://nymwell.com/zh-tw/docs/api/)
- [讓 AI 幫你買網域](https://nymwell.com/zh-tw/guides/buy-a-domain-with-ai/)
- [網域註冊 API 與 MCP 有什麼不同](https://nymwell.com/zh-tw/guides/domain-registrar-api-vs-mcp/)