Official Porkbun MCP Server

Buy Closeout

buy_closeout

Idempotent

Instructions

Spends account credit, or pays directly by card (pay_with_card) or in USDC (pay_with_usdc). Buys a closeout at its current price and claims the name. Confirm the total with the user first. cost_cents must equal totalPrice from get_closeout exactly — any other value is refused, so you cannot accidentally charge a price the user did not agree to. Use dry_run with cost 0 to quote without charging. The domain is reserved, not delivered. The provider releases it over the following days, so do not tell the user it is in their account: poll list_domains or watch the domain.registered webhook. Every post-charge failure refunds automatically and reports refunded:true. Losing the race to another buyer (CLOSEOUT_UNAVAILABLE) is not worth retrying on the same name — closeouts are first-come at a fixed price. CLOSEOUT_NOT_ELIGIBLE means support has blocked this account from auctions and closeouts over past-due invoices or an auction terms violation — do not retry, tell the user to contact support. There is no account-age or order-history requirement: eligibility is the same as registering a domain, plus verified email and phone.

How a purchase is paid. From prepaid account credit by default; a card saved at Porkbun is never charged by a purchase itself. Or directly, for this one purchase: pay_with_card: true (the user's card from their Stripe Link agent wallet, held and charged only if the purchase succeeds) or pay_with_usdc: true (USDC on Base over x402). If the credit is short, the call fails with INSUFFICIENT_FUNDS carrying cost, balance, shortfall, topUpAvailable and usdcAmountToCover (dry_run: true reports the same without charging). Ways forward, simplest first, always telling the user the dollar amount and getting their OK: (1) if they use Stripe Link, retry this exact call with pay_with_card: true; (2) if you can pay x402 (a wallet tool, or this server has PORKBUN_X402_PRIVATE_KEY), retry with pay_with_usdc: true; (3) when topUpAvailable is true a card is saved: top_up_account_credit (amount_cents at least topUpAmountToCover, or omit it for their configured amount), then retry; (4) add credit with top_up_with_card_mpp (Link) or top_up_with_usdc (for usdcAmountToCover, which allows for Coinbase's ~1% fee), then retry; (5) the user adds credit at https://porkbun.com/account/credit. If a purchase fails with VERIFICATION_REQUIRED, the phone (send_phone_verification_code then confirm_phone_verification) and the email (send_email_verification_code then confirm_email_verification) can both be verified without leaving the conversation, the user reading out each code. Suggest configure_auto_topup if they want credit refilled automatically. Money parameters are integer cents: state amounts to the user in dollars (cost_cents: 1108 is $11.08). If you do not move money on a user's behalf, hand it back instead: tell them the shortfall and that they can add it with buy account credit at https://porkbun.com/account/credit, then retry once they have.

Buying for a new or unfunded account: the whole path, including what only the human can do, is at https://porkbun.com/llms/guides/buy-a-domain-from-an-agent. Paying directly in USDC (no account credit needed): set pay_with_usdc: true. If this server has a wallet configured (PORKBUN_X402_PRIVATE_KEY, local installs only), the payment is signed and the purchase completes in this one call. Otherwise the result is status: PAYMENT_REQUIRED with a checkoutId, an x402Url and a payUrl, and nothing is charged: pay the x402Url with a wallet tool that pays x402 URLs (for example Coinbase's awal x402 pay <x402Url> --scheme auth-capture), or have the user pay the payUrl page, then call this tool again with the same arguments plus usdc_checkout_id. Tell the user the dollar amount first. If the purchase fails after payment, the payment is NOT returned to the wallet: it stays on the Porkbun account as credit (the error says keptAsCredit: true with the new balance), so retry without pay_with_usdc to buy from that credit.

Paying directly by card, with a hold (no account credit needed): set pay_with_card: true when the user pays with Stripe Link. The result is status: PAYMENT_REQUIRED with a payUrl and a cardPaymentId; nothing is charged. Pay the payUrl with an MPP wallet tool. With Link's CLI that is two commands: link-cli mpp pay <payUrl> -X POST --context "..." (context at least 100 characters) creates a spend request the user approves in Link; once approved, complete it with link-cli mpp pay <payUrl> --spend-request-id <lsrq_id> -X POST. That only authorizes the card. If link-cli answers NOT_AUTHENTICATED, run link-cli auth login first (a one-time device login the user approves). Then call this tool again with the same arguments plus card_payment_id: if the purchase succeeds the card is charged, and if it fails the hold is released and nothing is charged. The link works until expiresAt; if that passes before it is paid, call this tool again without card_payment_id for a fresh link instead of paying the old one.

Input Schema

Name	Required	Description
`cost`	No	Deprecated alias of `cost_cents`, same unit (integer US cents). Send `cost_cents` instead.
`domain`	Yes	Domain to buy, e.g. `example.com`
`dry_run`	No	Validate and price without charging or claiming.
`cost_cents`	No	Exact totalPrice from get_closeout. Use 0 only with dry_run. Required. Integer US cents: 803 means $8.03, not $803.
`pay_with_card`	No	Pay for this purchase by card from the user's Stripe Link agent wallet (MPP), with a hold: charged only if the purchase succeeds. Tell the user the amount first.
`pay_with_usdc`	No	Pay for this purchase directly in USDC on Base (x402) instead of from account credit. Tell the user the amount first.
`card_payment_id`	No	The cardPaymentId from an earlier PAYMENT_REQUIRED (pay_with_card), once its payUrl has been paid. Send it with the same arguments as that call.
`usdc_checkout_id`	No	The checkoutId from an earlier PAYMENT_REQUIRED result, once its x402Url or payUrl has been paid. Send it with the same arguments as that call.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.51.1Oct 14, 2026

addedInput schema / properties / card_payment_id

Added value: +{
+  "description": "The cardPaymentId from an earlier PAYMENT_REQUIRED (pay_with_card), once its payUrl has been paid. Send it with the same arguments as that call.",
+  "type": "string"
+}

addedInput schema / properties / pay_with_card

Added value: +{
+  "description": "Pay for this purchase by card from the user's Stripe Link agent wallet (MPP), with a hold: charged only if the purchase succeeds. Tell the user the amount first.",
+  "type": "boolean"
+}

addedInput schema / properties / pay_with_usdc

Added value: +{
+  "description": "Pay for this purchase directly in USDC on Base (x402) instead of from account credit. Tell the user the amount first.",
+  "type": "boolean"
+}

addedInput schema / properties / usdc_checkout_id

Added value: +{
+  "description": "The checkoutId from an earlier PAYMENT_REQUIRED result, once its x402Url or payUrl has been paid. Send it with the same arguments as that call.",
+  "type": "string"
+}

Addedv0.39.4Oct 1, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only state readOnlyHint=false, idempotentHint=true, and destructiveHint=false; the description carries the real behavioral burden. It discloses the critical surprise that the domain is reserved not delivered, that post-charge failures auto-refund with refunded:true, that a failed x402 payment stays as account credit (keptAsCredit:true), and it documents specific error codes and their required agent response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first paragraph is tightly front-loaded with the essential facts, and bold headers aid scanning. However, the piece runs to roughly 900 words with substantial repetition: the USDC flow and card flow are each explained twice, and the 'tell the user the dollar amount first' instruction recurs several times. Useful but not economical.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a money-moving tool with no output schema, the description is unusually complete: it enumerates result states (PAYMENT_REQUIRED with checkoutId/x402Url/payUrl, PAYMENT_REQUIRED with cardPaymentId, INSUFFICIENT_FUNDS fields, VERIFICATION_REQUIRED), the full payment lifecycle, and the exact human-only steps. An agent has everything needed to call and recover from this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the exact-match constraint on cost_cents is framed as a user-protection guarantee ('any other value is refused'), and the payment/hold semantics of card_payment_id and usdc_checkout_id are explained in context. This goes modestly beyond the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource ('Buys a closeout at its current price and claims the name') and implicitly distinguishes it from register_domain, get_closeout, and search_closeouts. An agent knows exactly what this tool accomplishes without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly covers when to use dry_run, when to choose pay_with_card vs pay_with_usdc vs account credit, and enumerates five ordered recovery paths (top_up_account_credit, top_up_with_card_mpp, top_up_with_usdc, manual credit). It also names when NOT to retry (CLOSEOUT_UNAVAILABLE, CLOSEOUT_NOT_ELIGIBLE) and hands off to sibling tools by name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Buy Closeout

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools