# Add account credit with USDC (x402)

Everything you buy over the Porkbun API is paid from prepaid **account credit**.
When an order fails with `INSUFFICIENT_FUNDS` and the account has no saved card,
the API can open a USDC checkout that tops the account up, and an AI agent with
a crypto wallet can pay it itself over **x402**, with no page and no person in
the loop. A person can pay the same checkout on a Coinbase page instead.

This is the same "Use Crypto" option as on porkbun.com: USDC on the Base
network, through Coinbase Business.

## How it works

1. You ask for a checkout for an amount of credit (`POST /account/topupCrypto`).
   Nothing is charged by this call.
2. The response has two ways to pay the same checkout:
   - **`x402Url`**: for an agent with a crypto wallet. x402 is an open payment
     standard built on HTTP status 402 ("Payment Required"): the wallet pays
     the URL with a gasless USDC transfer on Base.
   - **`payUrl`**: a Coinbase page where a person pays, from a Coinbase account
     or any wallet holding USDC on Base.
3. Coinbase confirms the payment (usually within a minute) and Porkbun adds the
   credit to the account, less Coinbase's network fee (about $0.01).
4. You check `GET /account/topupCryptoStatus/{checkoutId}` until `state` is
   `COMPLETED`, then retry the order that needed the credit.

## 1. Open a checkout

```
POST /api/json/v3/account/topupCrypto
{"apikey":"pk1_...","secretapikey":"sk1_...","amount":1500}
```

`amount` is integer US cents, from 500 ($5.00) to 50000 ($500.00). Send
`"dryRun": true` to check the account is eligible without creating anything.

```json
{
  "status": "SUCCESS",
  "checkoutId": "6abeec97d979cfdc17c60dbe",
  "amount_cents": 1500,
  "currency": "USDC",
  "network": "base",
  "payUrl": "https://payments.coinbase.com/payment-sessions/paymentSession_...",
  "x402Url": "https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_.../authorizations/x402",
  "expiresAt": "2026-10-02T23:28:00Z"
}
```

A checkout is single-use and expires after about 24 hours.

## 2. Pay it

**An agent with a wallet** pays `x402Url` with its x402 client. Coinbase's
Agentic Wallet and Wallet MCP ("make an x402 request") do this out of the box.
Tell the user the dollar amount and get their OK first: on-chain payments
cannot be reversed.

**A person** opens `payUrl` and pays from a Coinbase account or a wallet holding
USDC on Base.

## 3. Wait for the credit

```
GET /api/json/v3/account/topupCryptoStatus/6abeec97d979cfdc17c60dbe
```

| `state` | Meaning |
|---|---|
| `ACTIVE` | Not paid yet. |
| `PROCESSING` | Paid; the credit is being added. Check again in a few seconds. |
| `COMPLETED` | Credited (`credited: true`). `balance_cents` shows the new balance. |
| `EXPIRED` / `FAILED` | Not paid in time, or the payment failed. Open a new checkout. |

Then retry the original request unchanged.

## From the MCP server

On the full server (`https://mcp.porkbun.com/mcp`, or the npm package) the
tools are `top_up_with_usdc` and `get_usdc_topup_status`. They are not offered
on the versions in the Claude and ChatGPT app directories, which do not move
money.

## Who can use it

The same rules as the website's crypto option:

- The account's email and phone are verified (`VERIFICATION_REQUIRED` otherwise).
- The account is more than 7 days old, and not limited to bank-transfer credit
  (`CRYPTO_NOT_AVAILABLE`, with the reason in the message).
- Up to 10 checkouts per account per day (`CRYPTO_TOPUP_LIMIT`).
- Not on sandbox keys (`SANDBOX_UNSUPPORTED`): use `/sandbox/topup` for test
  credit.

Each error carries a `next_action` describing what to do. The account's monthly
spend limit still applies to what the credit is spent on.

## Other ways to add credit

- `POST /account/topup` charges a card already saved on the account (ask the
  user first).
- On porkbun.com, Account Credit: card, bank transfer or crypto.


---

## 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