---
title: 給 AI Agent 的 Nymwell 指南
description: AI Agent 的完整流程：查網域、把購買連結交給使用者、透過 MCP 連線，以及如何解讀狀態與錯誤。
---

# 給 AI Agent 的 Nymwell 指南

這頁寫給 AI Agent 照著做。英文原文在 https://nymwell.com/agents.md。

- 查網域、比價格：不需要帳號，也不需要 key。
- 購買：交給使用者一個連結。他用 Google 登入、看到鎖定的價格後刷卡付款。Agent 永遠不付款。
- 代為管理帳戶（報價、結帳、續約、轉入、DNS）：連到 `https://nymwell.com/mcp/account`，使用者用 Google 登入一次。

先確認目前開放哪些功能：`GET https://nymwell.com/api/v1/status`。`capabilities.registration` 與 `capabilities.payments` 都是 true 時才能購買。

## 什麼時候用 Nymwell

使用者請你找、查、發想或比較網域名稱；想買或註冊網域；想續約、從其他註冊商轉入，或把網域指到網站或 Email 服務。

## 1. 查詢（公開）

REST、JSON，每個 client 每分鐘最多 30 次查詢：

| 請求 | 回答 |
| --- | --- |
| `GET https://nymwell.com/api/v1/domains/search?domain=example.com` | 單一網域 |
| `GET https://nymwell.com/api/v1/domains/search?q=example&tlds=com,ai,io` | 同一個名稱搭配多個結尾（最多 20 個） |
| `GET https://nymwell.com/api/v1/domains/suggest?q=coffee` | 註冊商現在能賣的建議名稱 |
| `GET https://nymwell.com/api/v1/domains/tld-info?tlds=ai,io` | 各結尾的價格與規則 |
| `GET https://nymwell.com/api/v1/domains/screen?q=example` | 公開紀錄初篩（RDAP 與 DNS），不代表可註冊 |

可以註冊的網域會附 `tier`（`standard` 或 `premium`）、`price_display`、`renewal_display` 與 `buy_url`。無法註冊的網域 `available` 為 false，並附 `reason`：`domain_unavailable`（已被註冊）、`extension_not_supported`（Nymwell 不賣這個結尾）或 `extension_disallows_registration`（註冊局暫停受理）。`premium` 代表比該結尾一般價格高，請告訴使用者。

`price_display` 是首期價格（多數結尾一年，.ai 為兩年），`renewal_display` 是之後同樣年限的續約價格，兩個都要說。

## 2. 請使用者購買

把 `buy_url` 原樣交給使用者，例如 `https://nymwell.com/buy?domain=example-brand.com`，加上 `&lang=zh-tw` 會顯示繁體中文。

使用者會經歷：

1. 用 Google 登入，第一次登入會自動建立帳戶與工作空間。
2. 看到價格，保留 40 分鐘。
3. 第一次購買時填寫網域登記人並同意條款。
4. 在 Stripe Checkout 刷卡，付款就是本人核准。
5. 註冊商完成註冊，控制台會顯示結果；卡片會保存給自動續約使用，可以關閉。

可以這樣說：「example-brand.com 可以註冊，首年 US$14.49，之後每年 US$21.99。在這裡購買：https://nymwell.com/buy?domain=example-brand.com（用 Google 登入後在 Nymwell 付款）。」

## 3. 透過 MCP 連線

Streamable HTTP，以 POST 傳 JSON-RPC。兩個位址提供同一組工具：

| 位址 | 登入 | 可以做什麼 |
| --- | --- | --- |
| `https://nymwell.com/mcp` | 不需要 | 查詢、價格、結尾規則、DNS 預設、購買連結。帳戶工具會回覆如何登入。 |
| `https://nymwell.com/mcp/account` | Google 登入一次（OAuth 2.1） | 全部，作用在使用者的工作空間 |

- claude.ai 或 Claude Desktop：設定 → Connectors → 新增自訂 connector → `https://nymwell.com/mcp/account`。
- ChatGPT：以開發者模式新增 connector，填 `https://nymwell.com/mcp/account`，驗證選 OAuth。
- Claude Code：`claude mcp add --transport http nymwell https://nymwell.com/mcp/account`，再執行 `/mcp` 選 Authenticate。
- Codex：`codex mcp add nymwell --url https://nymwell.com/mcp/account`，再執行 `codex mcp login nymwell`。

不登入、只查詢：

```bash
claude mcp add --transport http nymwell https://nymwell.com/mcp
```

## 4. 代為管理帳戶

連到 `https://nymwell.com/mcp/account` 後：

1. `get_quote`，`action` 為 `register`、`renew` 或 `transfer`，價格鎖定 40 分鐘。
2. `purchase_domain` 回傳 `checkout_url`，交給使用者付款，付款就是本人核准。
3. 用 `get_order` 查進度，看 `workflow.state`：`in_progress` 或 `blocked` 稍後再查；`action_required` 把 `workflow.action.url` 交給使用者；`succeeded` 與 `failed` 是最終結果（`failed` 會附 `workflow.error`）。
4. `apply_dns_preset` 或 `stage_dns_change` 準備 DNS 變更，等擁有者在控制台核准後才會生效；在那之前 `workflow.state` 是 `action_required`，`list_approvals` 可以看每筆變更的進度。

轉入用的授權碼由擁有者在控制台輸入，絕不作為工具參數。腳本與伺服器也可以改用 agent key（`X-Nymwell-Key`），由已登入的擁有者在「AI Agents」建立；絕不要請使用者把 key 貼進對話。

## 規則

- Agent 永遠不付款、不輸入卡號、不核准，也沒有核准用的工具。
- 不要在對話中索取 agent key、卡號或授權碼。
- 可否註冊與價格只以 `search_domains`、`suggest_domains` 或報價為準；DNS、WHOIS、RDAP 與 `screen_domains` 只是初篩。
- 沒有 Nymwell 明確回覆成功之前，不要說購買、續約、轉入或 DNS 變更已完成。

## 錯誤

| 錯誤 | 怎麼處理 |
| --- | --- |
| `authentication_required` | 這個工具作用在使用者帳戶：給他 `buy_url`，或改連 `https://nymwell.com/mcp/account` 讓他登入 |
| `insufficient_scope` | agent key 缺少這個權限：改用 `/mcp/account`，或請使用者重新建立 key |
| `registrant_required`（409） | 已登入的擁有者到 https://nymwell.com/app/billing/#registrant 填寫網域登記人 |
| `rate_limited`（429） | 等 `retry_after_seconds` 秒 |
| `domain_unavailable` | 已被註冊，請換名稱 |
| `registrar_funds_low`、`integration_not_configured` | 暫停購買，沒有任何收費，請稍後再試 |

完整狀態與錯誤碼：https://nymwell.com/zh-tw/docs/reference/