POST /v1/x402/refill

Fund prepaid USDC with a Bearer key. No browser. The payer must be the key's own wallet (403 otherwise, refused before payment is taken).

Requires Authorization: Bearer pzero_…. Missing or invalid Bearer → 401. A session cookie (pzero_session, from Privy sign-in) is rejected on this route. Refill is Bearer-only, not browser session auth.

Refill moves balance only. It mints no key.

curl -X POST "https://api.pzero.studio/v1/x402/refill" \
  -H "Authorization: Bearer pzero_..." \
  -H "Content-Type: application/json" \
  -d '{ "amountMicroUsdc": 10000000 }'

Flow

1. POST amountMicroUsdc (integer micro-USDC; 1 USDC = 1_000_000. Not a decimal string).
2. Omit X-PAYMENT on the first call; the server returns 402 with accepts.
3. Sign the EIP-3009 exact payment and retry with X-PAYMENT and a byte-identical body.
4. 200 records the top-up as pending until confirmation depth. Poll GET /v1/agent/me until confirmedUsdc covers spend. Only confirmed balance funds inference.

Whenever the facilitator returns a settlement receipt, the response carries X-PAYMENT-RESPONSE (base64, CORS-exposed). Keep it: it proves a payment landed even if the request then failed. A settlement that failed after broadcasting produces no receipt; on that path read transaction from the 409 body instead.

A payment that settled but could not become balance answers 409 with transaction and no accepts. Keep the hash. Do not pay again. reconciling: true means queued credit from the chain; false needs support. A 402 always carries accepts and means money has not moved.

	Micro-USDC	USDC
Minimum	1,000,000	$1
Recommended	10,000,000	$10
Maximum	1,000,000,000	$1,000

Success

200 returns confirmedUsdc, pendingUsdc, topUpAmountUsdc, walletAddress, confirmationBlocks, and idempotent (true when this settlement was already credited).

Situation	Response
Settled and credited	200 as above
Same settlement replayed	200 with idempotent: true
Missing/invalid Bearer or session cookie	401
Payer ≠ key's wallet	403 (before settlement)

Refill early rather than at zero. Fresh credit is pending for the confirmation window, so waiting until empty stalls that long. Size against burn rate plus confirmation wait.

Inference is never paid per request. Credit is prepaid.

Related routes (not on this tab)

Humans in the browser fund via session top-up in Studio (Credits), not this route. First key without a browser: POST /v1/x402/signup (payment is the credential; no Bearer).

Next

• GET /v1/agent/me
• Errors & limits