# 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 | 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 email and phone | The agent, with the human reading out each code | `send_email_verification_code` / `confirm_email_verification` and `send_phone_verification_code` / `confirm_phone_verification` (or the human clicks the email link) |
| 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).

Then call `ping`: it returns `account`, the username of the Porkbun account the
agent is connected to. Confirm it is the one the human means, especially if
they have more than one; a domain in another account comes back as
`DOMAIN_NOT_FOUND`, which names the account too.

## 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 agent can do both, with the human reading out the codes.

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`, `send_email_verification_code`
   emails a code to the address on the account; ask for it, then
   `confirm_email_verification`. Clicking the link in that email works too.

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.

If the name is taken, it may still be for sale: `search_aftermarket` shows any
listing, with its price, whether that is a buy-now price, a minimum offer or a
current bid (`saleType`), and a `buyUrl`. Aftermarket names are bought on
porkbun.com by the human, not by the agent.

## 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** | `register_domain` with `pay_with_card: true` returns `PAYMENT_REQUIRED` with a `payUrl`; pay it from their Link wallet (`link-cli mpp pay <payUrl> -X POST`, they approve in Link), then call `register_domain` again with `card_payment_id`. The card is only held until the registration succeeds, and released if it fails |
| **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 **by card** (`pay_with_card`) is the cleanest when it is available: the card is authorized first, charged only if the registration succeeds, and released if it fails. Details: [Pay with the user's card (MPP)](https://porkbun.com/llms/guides/pay-with-card-mpp).

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. Every registration also comes with a free trial email mailbox, waiting
to be set up: `setup_mailbox` gives it an address at no cost
([Set up a mailbox](https://porkbun.com/llms/guides/set-up-a-mailbox)).

## 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`).
- **Domains already owned** (renewing, DNS, contacts) need API access turned
  on for that domain. `list_domains` and `get_domain` show it as `apiAccess`;
  check before starting, because only the human can turn it on, in account
  settings (`API_ACCESS_DISABLED` otherwise).
- **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