# Buy a domain from an agent, start to finish

The whole path from "the human wants a domain" to "it is registered", for an AI
agent working over the Porkbun MCP server or the API. Most of it the agent does
itself; a few steps prove who the human is and have to happen in their browser,
once.

## Who does what

| Step | Who | How |
|---|---|---|
| Create a Porkbun account, click the email verification link | The human, in a browser | https://porkbun.com/account/create. Not possible over MCP or the API |
| Connect the agent | The human approves in a browser | Hosted connector: sign in and approve. Local server: approve a key request (below) |
| Verify the phone | The agent, with the human reading out a code | `send_phone_verification_code`, then `confirm_phone_verification` |
| Check the name and price | The agent | `check_domain` |
| Pay | The agent, or the human for a browser payment | Account credit, or USDC directly (below) |
| Register | The agent | `register_domain` |

Nothing is charged until every check has passed: verification, availability,
price, eligibility and the account's monthly limit are all checked before any
payment is asked for, so starting a purchase is safe.

## 1. Connect

Pick by what the agent can do:

- **Web chat or GUI app** (ChatGPT, claude.ai, Claude Desktop): the human adds
  `https://mcp.porkbun.com/mcp` as a connector, signs in and approves. No keys.
  If they have no Porkbun account yet, they can create one from that sign-in
  page; it comes back to the approval.
- **Coding agent that runs commands** (Claude Code, Cursor, Codex): either the
  same hosted connector (`claude mcp add --transport http porkbun
  https://mcp.porkbun.com/mcp`), or the local server
  (`npx -y @porkbunllc/mcp-server`) with API keys. To get keys without the
  human copying a secret, use the browser-approved key handoff in the
  [agent setup prompt](https://porkbun.com/llms/agent-setup); the human can
  create an account on the approval page if they need one.

Only the local server can pay in USDC by itself (it can hold a wallet key).

## 2. Verify the account

Purchases need a verified email and phone. New accounts are not asked for the
phone at signup, so expect `VERIFICATION_REQUIRED` on the first purchase, or
check first: the phone part the agent can do.

1. `send_phone_verification_code` texts a code to the number on the account
   (`channel: "call"` reads it out if the text does not arrive).
2. Ask the human for the code, then `confirm_phone_verification` with it.
3. If the result says `emailVerified: false`, the human has to click the link in
   the verification email (resendable from account settings). Wait for them.

Details: [Verify an account from an agent](https://porkbun.com/llms/guides/verify-the-account).

## 3. Check the name

`check_domain` (or `check_domains` for several) gives availability and the price
in cents. Tell the human the dollar amount and get their go-ahead before
buying. `register_domain` with `dry_run: true` rehearses the whole purchase
without charging.

## 4. Choose how to pay

| Situation | What to do |
|---|---|
| The account has enough credit | `register_domain` as normal; it spends credit |
| A card is saved on the account | `top_up_account_credit` (with the human's OK), then register |
| The human has Stripe Link | `top_up_with_card_mpp`, pay its link from their Link wallet, then register |
| **Local server with `PORKBUN_X402_PRIVATE_KEY`** | `register_domain` with `pay_with_usdc: true`: the server pays in USDC and registers in one call |
| **You have a wallet tool that pays x402 URLs** (a wallet MCP, Coinbase's `awal` CLI) | `register_domain` with `pay_with_usdc: true` returns `PAYMENT_REQUIRED` with `x402Url`; pay it (`awal x402 pay <x402Url> --scheme auth-capture`), then call `register_domain` again with the same arguments plus `usdc_checkout_id` |
| **No wallet, but the human can pay in a browser** | Same as above, but give the human the `payUrl` (a Coinbase page) and call again with `usdc_checkout_id` once they say it is paid |
| None of these | Tell the human the shortfall and send them to https://porkbun.com/account/credit |

Paying directly in USDC needs no account credit and charges exactly the price.
**If the registration fails after payment, the USDC is not sent back to the
wallet: it stays on the account as Porkbun account credit**, and the error says
so (`payment.keptAsCredit: true`, with the new balance). Retry the same purchase
without `pay_with_usdc` to buy from that credit, or use it for anything else. Details: [Pay with USDC (x402)](https://porkbun.com/llms/guides/pay-with-usdc-x402).

When you call again with `usdc_checkout_id`:

- `PAYMENT_REQUIRED`: not paid yet. Pay, then repeat.
- `PAYMENT_PENDING`: paid and settling. Wait `retryAfter` seconds and repeat.
  **Do not pay again.**
- `PAYMENT_MISMATCH`: the arguments differ from the call that returned the
  checkout. Repeat that call unchanged.
- `PAYMENT_ALREADY_USED`: that checkout was already used. Either it bought
  something, or nobody came back for it within an hour and it was added to the
  account's credit. Check whether the domain is registered; if not, buy it from
  credit (without `pay_with_usdc`).

## 5. Register and confirm

A successful `register_domain` returns the order. When paid in USDC it also
returns `payment` (`paidWith: "usdc"`, the amount and the checkout). Confirm with
`get_domain` or `list_domains`, then go on to DNS (`create_dns_record`) or
hosting.

## Limits that apply throughout

- **Monthly limit:** API purchases and credit added over the API are each capped
  per month at the account's limit, $100 until the human sets their own at
  https://porkbun.com/account/api (`MONTHLY_SPEND_LIMIT_EXCEEDED`). Only the
  human can raise it. Details: [Cap what an agent can spend](https://porkbun.com/llms/guides/spend-limits).
- **A single API registration** cannot exceed $100 (`ORDER_TOO_LARGE`).
- **Premium names** and a few TLDs cannot be registered over the API; the human
  registers those on the website.
- Every error carries `code` and `next_action`; follow `next_action`.


---

## More

- Guides (how-tos): https://porkbun.com/llms/guides
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Short overview: https://porkbun.com/llms.txt
- Official MCP server: https://porkbun.com/mcp (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api