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

# How ZeroClick works

> The life of one paid agent request: transparent proxying, the single priced 402 challenge, the signed forward, the allowance check, and settlement.

ZeroClick is a transparent paid proxy in front of your API. An agent calls your pay URL, `https://acme.pay.zeroclick.io/<path>`, with exactly the request it would send your API directly: the same method, the same path and query, the same body. ZeroClick prices the call, collects payment over [x402 or MPP](/concepts/payment-protocols), and forwards the request to your upstream base URL. It signs the forward so your backend can trust it. This page follows one pay-as-you-go request through that lifecycle at the protocol level; the [quickstart](/quickstart) covers the integration itself.

The full flow is two round trips from the agent's side. The agent talks only to your pay URL, and your API talks only to ZeroClick:

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant A as Buying agent
    participant Z as ZeroClick<br/>(acme.pay.zeroclick.io)
    participant S as Your API<br/>(upstream base URL)

    rect rgba(25, 25, 255, 0.06)
    note over A,S: Round trip 1: price the request
    A->>Z: POST /v1/product-watch
    Z->>S: same request, signed<br/>zc-request-id + zc-signature (no agent id)
    S-->>Z: 402 refusal with declared usage
    Z-->>A: one priced 402 challenge<br/>payment-required and www-authenticate
    end

    rect rgba(25, 25, 255, 0.06)
    note over A,S: Round trip 2: pay and get served
    A->>Z: identical request + payment proof<br/>x-payment or authorization
    Z->>S: same request, signed<br/>zc-request-id + zc-agent-id + zc-signature
    S->>Z: POST /v1/usage/check
    Z-->>S: allowed
    S-->>Z: 200 + zc-usage header
    Z-->>A: 200 response + zc-billing header
    end
```

The two arrows in the middle of round trip 2 are your backend calling ZeroClick's REST API at `api.zeroclick.io`; every other arrow carries the agent's own request and response. ZeroClick strips the `zc-usage` header before the response reaches the agent.

<Steps>
  <Step title="An agent calls the pay URL">
    The agent sends its normal request to `https://acme.pay.zeroclick.io/v1/product-watch`: no signup, no API key, no ZeroClick-specific headers. The pay URL host names the seller; the method, path, query, and body are your API's own.
  </Step>

  <Step title="ZeroClick answers with one priced 402">
    An unpaid request needs a price before ZeroClick can charge for it. For pay-as-you-go, ZeroClick forwards it upstream as a signed **anonymous probe**: the forward carries `zc-request-id` and `zc-signature` but no `zc-agent-id`. Your API refuses the probe with the exact body `{"error":"payment_required","serviceSlug":"product-watch","usage":[{"meterSlug":"requests","quantity":1}]}`. ZeroClick prices that declared usage against your catalog and answers the agent with a single `402 payment_required` challenge.

    The challenge arrives in one response, several ways at once: the body carries the exact amount (`payment.amountUsd`) and a block per protocol. The full signable challenges ride in the `payment-required` (x402) and `www-authenticate` (MPP) response headers. The total is one priced 402, so a stock single-payment client completes the flow unmodified.
  </Step>

  <Step title="The agent pays and retries byte-identically">
    The agent pays the challenge with its wallet and retries the identical request with the proof attached: the signed x402 payload in the `x-payment` header, or an MPP credential in `authorization: Bearer …`. The payment binds to the challenged request's body digest, so the retry must carry the same bytes. ZeroClick refuses a different body with `409 payment_request_mismatch`.
  </Step>

  <Step title="ZeroClick verifies, signs, and forwards">
    ZeroClick verifies the payment, binds the paying wallet to a [buyer agent](/concepts/agents-and-access) (`agt_…`), and forwards the request to your `upstreamBaseUrl`. It strips inbound `zc-*` and payment headers, then sets its own three: `zc-request-id`, `zc-agent-id`, and `zc-signature`. The signature is an HMAC over the method, path, body digest, and both ids (see the [signature spec](/integrate/signature-spec)).
  </Step>

  <Step title="Your API verifies, checks the allowance, and serves">
    Your backend [verifies the signature](/integrate/verify-requests) first, then asks `POST /v1/usage/check` whether the buyer's plan covers the declared usage. The check is a pure decision: it [records nothing and burns nothing](/concepts/usage-and-allowances). If the check allows, your API does the work. If it denies, your API returns the 402 refusal body. ZeroClick turns that refusal into the buyer's next challenge.
  </Step>

  <Step title="Usage settles and the response returns">
    Your API settles actual usage synchronously, in a `zc-usage` response header on the 2xx response (preferred), or reports it asynchronously via `POST /v1/usage`. ZeroClick records the usage and settles the payment, at actual usage when the challenge priced a [ceiling](/integrate/charge-up-to-a-maximum). It strips `zc-usage` so the agent never sees it, then returns your response to the agent with a `zc-billing` header.
  </Step>
</Steps>

## Who does what

| Actor     | Responsibility                                                                                                                          |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Agent     | Discovers the storefront, sends normal API requests, signs and pays 402 challenges, retries with the proof attached.                    |
| ZeroClick | Prices the challenge, verifies the payment, resolves wallet identity, signs and forwards the request, records usage, settles the money. |
| Your API  | Verifies `zc-signature`, checks the allowance, does the work, returns the exact 402 refusal on denial, settles usage.                   |

The seller side of this table is the whole integration: verify, check, serve, settle. The [integration overview](/integrate/overview) states that contract on one page, and the [seller SDKs](/sdks/overview) implement it.

## One id ties it together

`zc-request-id` (`zcreq_…`) is the correlation spine. ZeroClick mints it when a request first arrives and reuses it end to end. The anonymous probe, the challenge body (as `zcRequestId`), the paid retry, your allowance check, and the recorded usage events all carry the same id. Log it on every guarded request, and you can trace any transaction across your systems and the dashboard.

The agent's side closes the loop with `zc-billing`, a response header on every per-call paid response that reconciles the authorized amount against the charged amount:

```json theme={null}
{
  "status": "settled",
  "authorizedUsd": "0.016384",
  "chargedUsd": "0.009046",
  "remainderUsd": "0.007338",
  "remainderHandling": "escrow_returned",
  "settleTransactionHash": "0x…"
}
```

For a fixed-quantity request, the authorized and charged amounts match. For a ceiling-priced request, the authorized amount is the most the agent could have paid, and the remainder went back to its wallet. `"status": "settling"` means on-chain settlement has not finished, so the final amounts are not stamped yet.

<Note>
  Agents on purchased plans follow the same lifecycle with one difference: a credit or subscription purchase happens once, up front, through the storefront. After that, each call carries an identity proof instead of a fresh payment, and covered calls forward without a new 402. See [plans and pricing](/concepts/plans-and-pricing).
</Note>

The [headers reference](/resources/headers) catalogs every header in this flow.