> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment protocols

> How ZeroClick uses x402 and MPP: challenge and proof headers, minted deposit addresses, reserve rails for ceiling charges, and settlement.

ZeroClick accepts two agent payment protocols: [x402](https://www.x402.org) and MPP, the [Machine Payments Protocol](https://mpp.dev). Both settle USDC. This page explains how ZeroClick uses them, not how they work internally; as a seller you never implement either. Your API sees only signed, already-paid requests, and the billing guard is identical whichever rail the buyer chose.

## The two rails

Both protocols follow the same loop: ZeroClick answers an unpaid request with the [single priced 402](/docs/concepts/how-zeroclick-works.md), the agent signs the challenge with its wallet, and the retry carries the proof in a standard header. An anonymous challenge offers both protocols and lets the buyer pick by paying; a buyer that already authenticated on one rail is challenged on that rail.

| | x402 | MPP |
| - | - | - |
| Challenge rides in | `payment-required` response header (and the standard x402 document in the 402 body) | `www-authenticate` response header |
| Proof rides in | `x-payment` request header (signed payment payload) | `authorization: Payment <credential>` request header |
| Settles | USDC on Base (`eip155:8453`) | USDC on Tempo |
| Fixed-quantity charges | `exact` scheme | one-shot charge |
| Ceiling charges | `upto` scheme (reserve, settle at actual) | session escrow channel |
| Receipt header on paid responses | `payment-response` | `payment-receipt` |

Inside the 402 body, each offered rail appears as a block under `protocols`, alongside ZeroClick's own `payment` block with the exact USD amount:

```json theme={null}
{
  "error": "payment_required",
  "zcRequestId": "zcreq_8h2m4x0q9k1f",
  "payment": { "id": "apay_…", "amountUsd": "0.010000" },
  "protocols": {
    "x402": { "x402Version": 2, "network": "eip155:8453", "scheme": "exact", "amount": "10000", "asset": "0x…" },
    "mpp": { "challengeId": "…", "method": "tempo", "intent": "charge" }
  }
}
```

The challenge an agent signs embeds ZeroClick's payment metadata (the `payment.id` and `zcRequestId` above), so the signed proof is all a retry needs. Identity-only challenges use the same machinery at amount zero: proving wallet control is always free, and nothing settles on-chain for them.

## Fixed charges settle after delivery on x402

An x402 `exact` payment is verified before ZeroClick forwards the request, but it settles on-chain only after your API returns a 2xx, and before ZeroClick releases your response to the agent. If the delivery fails, the buyer's signed authorization expires unused and no USDC moves. If the settlement cannot happen and nothing has moved (the wallet no longer covers it, the agent cancelled its authorization, or the authorization expired first), the agent gets a `402 payment_settlement_failed` instead of your response, and nothing is charged. An authorization that expires too soon to hold is settled before forwarding instead.

A 2xx with an empty body is a failed delivery too; see [empty responses](/docs/integrate/settle-usage.md#empty-responses-do-not-bill) for what counts as empty. An MPP one-shot charge transfers when the agent pays, so a failed delivery on that rail is not returned; the `zc-billing` header records it either way.

## ZeroClick mints the deposit address

Every priced challenge pays into a deposit (`payTo`) address that ZeroClick minted for that specific payment. Buyers pay exactly the address the challenge specifies. Sellers never publish, rotate, or even see these addresses.

## Ceiling charges need a reserve rail

A [ceiling-priced request](/docs/integrate/charge-up-to-a-maximum.md), one whose usage item declares a `maxQuantity`, authorizes the most the call could cost, but must charge only actual usage. That is possible only on the reserve-and-pay-actual rails, so a ceiling challenge offers exactly these:

* **x402 `upto`**: the wallet reserves the ceiling; ZeroClick settles the actual amount after delivery, and the reserved remainder never leaves the buyer's wallet.
* **MPP session escrow**: the buyer funds a channel to the ceiling and signs one voucher; ZeroClick closes the channel at actual usage, and the escrow refunds the rest. If the close ever fails, the buyer can force-close after the on-chain grace period, so escrowed funds are never stranded.

ZeroClick never offers one-shot prepay (`exact`, or the MPP charge) for a ceiling: that is what guarantees an unspent ceiling cannot get stuck as seller credit. If neither reserve rail is available for a capped price, ZeroClick refuses to mint an unpayable challenge and returns `503 capped_pricing_unavailable` instead. A failed delivery debits nothing on either rail, and every per-call paid response reconciles authorized versus charged in the `zc-billing` header.

Stateful sellers' plan purchases and top-ups settle the same way. A standing-account purchase only charges once the seller confirms the account is provisioned, so the purchase 402 offers the reserve rails at the plan price (and the card lane authorizes without capturing). Capture happens when provisioning is acknowledged; a failed provisioning releases the wallet reservation or voids the card authorization, and the buyer is never charged.

## Automatic Tempo payments for standing accounts

When a plan advertises `tempoAutomaticPayments` in its storefront manifest, a buyer can approve recurring charges separately from ordinary one-time purchases. The buyer reviews the seller's receiving address, price, billing interval, spending limits, and end date before signing an MPP `subscription` permission. The first subscription charge is part of that approval and funds the first service period; a buyer who already paid for a period waits until renewal is due. Later charges run from ZeroClick's hosted worker without the buyer's computer being online. A confirmed charge advances the existing account and sends the seller a new signed account write.

Tempo's native billing windows are fixed lengths: a daily plan is 1 day, a monthly plan is **every 30 days**, and a yearly plan is **every 365 days** from the first charge. They are not calendar-month or calendar-year dates. A buyer may choose an end date or leave the permission set to “until cancelled.” The latter uses a distant technical expiry, so the buyer should still cancel when they want billing to stop.

Automatic credit top-ups use a **second** standard Tempo `subscription` permission for the fixed refill amount, charged **at most once per day**. Buyers request it in the same signup as the plan by adding an `autoTopUp` block (`amountUsd`, `thresholdUsd`, `cooldownSeconds` of at least 86400, `dailyLimitUsd`, `monthlyLimitUsd`). Refills never charge at signup: they start after the first plan charge, when ZeroClick reads a fresh low balance and the buyer's cooldown and monthly limit allow it. An existing account can add refills later with a separate `kind: "top_up"` request.

Every signup step is an ordinary MPP `402`, so any MPP client can complete it. First, pay the plan's challenge and repeat the identical request with `Authorization: Payment <credential>`; the plan is then active. If refills were requested, send the identical request once more and pay the second challenge the same way. Each response includes `nextAction` describing what is left, and skipping the second step only skips refills. Clients that can sign two challenges at once may instead sign `topUp.challenge` from the first response and send it in the `ZC-Tempo-Top-Up` header alongside the plan credential. A failed top-up approval never blocks the plan.

Either permission can be cancelled independently at ZeroClick, which stops its worker from submitting new charges. An “until cancelled” permission has an on-chain technical expiry in 2100. Tempo enforces the exact amount, recipient, one charge per window, and expiry; ZeroClick also enforces the buyer's cooldown and monthly limits. Once a permission's first charge has installed its key on-chain, a buyer who wants to remove the wallet permission should also revoke that key on-chain. Before then there is no installed key to revoke, and cancelling at ZeroClick stops its worker from using the saved approval.

## Amounts and settlement

Two money rules shape what the rails carry:

* Amounts that settle on-chain as a single charge are **whole cents**: plan purchases, top-ups, subscription base prices, and pay-as-you-go rates. Catalog prices on credit and subscription plans keep 6-decimal precision, because they only burn prepaid balance. [Plans and pricing](/docs/concepts/plans-and-pricing.md) covers both rules.
* Buyers pay USDC, but your revenue settles to your connected Stripe account (in fiat or USDC, your choice). You never operate a wallet to sell through ZeroClick. Rail availability depends on the country where your business is established; see [supported countries](/docs/resources/supported-countries.md).

## Sellers stay protocol-agnostic

Nothing protocol-specific ever reaches your API. ZeroClick strips payment headers before forwarding, and your integration is the same four steps on every rail: verify the [signature](/docs/integrate/verify-requests.md), [check the allowance](/docs/integrate/check-allowances.md), serve, and [settle usage](/docs/integrate/settle-usage.md). When ZeroClick adds a new payment protocol, sellers ship nothing.

For the protocols themselves, see [x402.org](https://www.x402.org) and [mpp.dev](https://mpp.dev).

When buyer identity is also required, send its bearer in `ZC-Agent-Authorization: Bearer <access token>`. Keep `Authorization` for the MPP `Payment` credential; never combine credentials in one header.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.