USDC top-ups (x402)

---

title: USDC top-ups (x402) description: Top up your api14 USD balance with USDC on Base over the x402 protocol, so agents can pay from their own wallet without a card or checkout page. keywords: x402, pay API with USDC, crypto API payments, agent payments, USDC on Base, HTTP 402 payments, stablecoin top-up, machine payments

Agents can add balance on their own by paying USDC from a wallet. Payment uses x402, an open protocol built on HTTP 402 Payment Required: the server says what to pay, the client signs a USDC transfer authorization, and a facilitator settles it on chain. No card, no checkout page and no gas for the payer.

POST https://api14.com/api/v1/topup?amount_usd=25

The amount is in US dollars and is paid as the same amount of USDC. It must be between the minimum and maximum top-up (by default $5 and $5,000). Top-up bonuses apply as with card top-ups.

Flow

1. Call the endpoint with your API key and no payment. The response is 402 with the payment requirements in the PAYMENT-REQUIRED header (base64 JSON) and in the body.
2. Sign the requirements with your wallet and repeat the same request with the signed payment in the PAYMENT-SIGNATURE header.
3. The payment is verified and settled on chain. Only then is your balance credited, and the response is 200 with a PAYMENT-RESPONSE receipt header.

An x402 client library does steps 2 and 3 for you:

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch'
import { ExactEvmScheme } from '@x402/evm/exact/client'
import { privateKeyToAccount } from 'viem/accounts'

const wallet = privateKeyToAccount(process.env.AGENT_WALLET_KEY as `0x${string}`)
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(wallet) }],
  // The x402 client refuses payments above $1 by default. Raise the cap to your top-up size.
  spendControls: { maxAmountPerPayment: '$50' },
})

const res = await pay('https://api14.com/api/v1/topup?amount_usd=25', {
  method: 'POST',
  headers: { Authorization: 'Bearer sk-api14-...' },
})
console.log(await res.json())

Response

{
  "credited_usd": 25,
  "balance_usd": 67.18,
  "transaction": "0x5f2c...e91a",
  "network": "eip155:8453"
}

credited_usd includes any top-up bonus. The transaction hash is the payment's reference: quote it to support.

Payment requirements

Always pay to the payTo address in the requirements you receive, never to an address copied from elsewhere.

From the dashboard

People can pay the same way without writing code. On Billing, under Pay with crypto, enter an amount and pick your wallet: MetaMask, Coinbase Wallet, Rabby, Trust, OKX, Brave or any other browser wallet that supports Ethereum. The wallet switches to Base if needed and asks you to sign the USDC transfer. You pay no gas, and your balance updates as soon as the payment settles.

From an MCP agent

The MCP server has a topup_balance tool with the same flow: the payment travels in _meta["x402/payment"] instead of a header.

Errors

USDC refunds are sent back to the wallet that paid, see the refund policy.