> ## 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.
# Headers
> The zc-* and payment header reference for every direction: ZeroClick to your API, your API to ZeroClick, ZeroClick to the agent, and the agent to ZeroClick.
Four parties exchange headers on every paid request: the agent, ZeroClick's proxy, your API, and the response path back. This page lists every header per direction, with formats and realistic values. The `zc-request-id` value (`zcreq_…`) is the correlation spine. The same id flows through the challenge, the paid retry, the allowance check, and the usage record. See [how ZeroClick works](/concepts/how-zeroclick-works) for the lifecycle.
## ZeroClick to your API (request)
Headers ZeroClick sets on every request it forwards to your `upstreamBaseUrl`:
| Header | Example | Notes |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `zc-request-id` | `zcreq_8h2m4x0q9k1f` | Correlation id for this request. Echo it in `POST /v1/usage/check` as `zcRequestId`. |
| `zc-agent-id` | `agt_x7f2kq93bh0d` | The agent that made this call. Absent on signed anonymous probes: a valid, expected state used to price pay-as-you-go 402s. |
| `zc-anonymous-id` | `agt_x7f2kq93bh0d` | The same value as `zc-agent-id`, under the name that will eventually replace it. Present and absent in exactly the same cases. |
| `zc-buyer-id` | `byr_3n8v1c6t5j2w` | The person or company the agent belongs to. Sent only once that owner is known; absent means an anonymous agent. |
| `zc-signature` | see below | HMAC proof the request came from ZeroClick. Verify it before anything else. |
| `zc-sandbox` | `1` | Sent on sandbox test traffic only; branch to your own test mode on it. |
### `zc-agent-id` and `zc-buyer-id`
These answer two different questions, and a request can carry either one or both:
* `zc-agent-id` is **who called**. It is always the agent that executed this request, never some other agent that happens to have paid for the plan being drawn down.
* `zc-buyer-id` is **who they belong to**. One buyer can hold many agents; every one of them is entitled to everything the buyer owns.
| What you see | What it means |
| ------------- | ----------------------------------------------------------------------------------- |
| Neither | A signed anonymous probe. No identity has been established yet. |
| Agent id only | An anonymous agent: identified and billable, but not yet attached to a known owner. |
| Both | The agent belongs to that buyer and inherits the buyer's entitlements. |
Key per-caller state (rate limits, per-run scratch data) on `zc-agent-id`. Key per-customer state (history, tenancy, saved records, anything a human should still see after their agent is replaced) on `zc-buyer-id` when it is present, since a buyer can retire one agent and call you with the next. Two requests carrying the same `zc-buyer-id` under different agent ids are the same customer.
The signature covers `zc-agent-id`, not `zc-buyer-id`. Treat the buyer id as a fact ZeroClick asserts over the authenticated channel rather than as an independently proven one, and never let it alone unlock records you would not release to the agent id it arrived with.
Before forwarding, ZeroClick strips every inbound `zc-*` and `x-zc-*` header plus `x-payment`, `payment`, and `payment-signature`, then sets its own. An agent can never spoof these values. Any upstream auth you configured between ZeroClick and your API passes through unchanged.
### `zc-signature`
```text theme={null}
zc-signature: t=1785254400,kid=hsec_k5nq0v7m3d8p,v1=9f2c7d41a8e05b6c3f1d92e47ab08c5d6e1f3a29b47c80d5e2f16a3b4c5d6e7f
```
The grammar is `t=,kid=,v1=<64 lowercase hex>`; sandbox traffic appends `,sb=1`. `t` is the signing time (verify within a tolerance, 300 seconds by default). `kid` names the signing secret so you can select the right one during rotation. `v1` is the HMAC-SHA256 (constant-time compare) over a six-field canonical string: `t`, the uppercased method, the raw path and query, the SHA-256 hex of the raw body bytes, the `zc-request-id` value, and the `zc-agent-id` value or empty string. The signed canonical is identical for sandbox and live traffic; verifiers that parse only `t`/`kid`/`v1` ignore the trailing `sb=1`. Full byte-level rules: [signature spec](/integrate/signature-spec).
## Your API to ZeroClick (response)
| Header | Example | Notes |
| ---------- | --------- | -------------------------------------------------------------- |
| `zc-usage` | see below | Settles usage synchronously on a delivered response. 2xx only. |
### `zc-usage`
```text theme={null}
zc-usage: [{"serviceSlug":"product-watch","meterSlug":"requests","quantity":1},{"serviceSlug":"product-watch","meterSlug":"output_tokens","quantity":842}]
```
A JSON array of `{ "serviceSlug", "meterSlug", "quantity" }` items; `quantity` is an integer from 0 to 2,147,483,647 (0 settles a capped meter at zero). Set it only on a 2xx response that delivered. A 4xx must not carry it. ZeroClick strips the header before the agent sees the response. This is the preferred way to settle usage; [settle usage](/integrate/settle-usage) covers it against the async `POST /v1/usage` alternative.
If billing fails after your API already delivered (a malformed header, a denial, or a settlement exception), ZeroClick does not drop the response. It returns the body to the agent and names the failure in the `zc-usage-error` response header. The payment stays observable rather than silently lost.
## ZeroClick to the agent (response)
| Header | When | Carries |
| ------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `payment-required` | 402 challenges | The full signable x402 challenge (the complete PaymentRequired document, header-encoded). |
| `www-authenticate` | 402 challenges | The full signable MPP challenge. |
| `zc-billing` | Responses to requests paid with a per-request payment | The settlement summary: authorized vs. charged vs. remainder. |
| `payment-response` | Paid x402 responses | The x402 settle receipt, base64-encoded: loggable proof of what settled. |
| `payment-receipt` | Paid MPP responses | The serialized MPP receipt. |
| `zc-usage-error` | Delivered responses whose billing failed | A machine code: an allowance denial reason, `invalid_usage_header`, or `settlement_failed`. |
| `zc-usage-adjusted` | Settled quantities differ from reported | JSON array of `{ "meterSlug", "reportedQuantity", "settledQuantity" }`. Reports beyond the authorization settle at the cap or at zero. |
Identity-only responses carry no receipt header. Free-mode responses covered by included units carry no `zc-billing`: there was no per-request payment to settle.
### `zc-billing`
```text theme={null}
zc-billing: {"status":"settled","authorizedUsd":"1.250000","chargedUsd":"0.421000","remainderUsd":"0.829000","remainderHandling":"escrow_returned","settleTransactionHash":"0x9c2e..."}
```
| Field | Meaning |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `settled` once the settlement committed; `settling` while it is still finishing (the amounts below are withheld until final). |
| `authorizedUsd` | What the agent's payment authorized. On [ceiling-priced requests](/integrate/charge-up-to-a-maximum) this is the ceiling, not the charge. |
| `chargedUsd` | What the request actually cost, read back from the settlement ledger. |
| `remainderUsd` | `authorizedUsd` minus `chargedUsd`. |
| `remainderHandling` | Where the remainder went: `credited` (added to the buyer's balance with this seller), `escrow_returned` (it never left the wallet, or was refunded from escrow), or `escrow_expired` (the hold lapsed unsettled; the buyer kept the full ceiling). |
| `settleTransactionHash` | The on-chain settle transaction, when one exists. |
## The agent to ZeroClick (request)
| Header | Example | Notes |
| --------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `x-payment` | `x-payment: ` | The signed x402 proof answering a `payment-required` challenge. Also accepted under the `payment-signature` name. |
| `authorization` | `authorization: Bearer ` | The signed MPP credential answering a `www-authenticate` challenge. |
| `zc-mode` | `zc-mode: free` | Opt-in to free included-units coverage on pay-as-you-go. Any other value, or no header, is paid mode. |
The proof carries everything: the challenge an agent signs embeds ZeroClick's payment metadata, so the paid retry needs no other headers. The retry must be byte-identical to the challenged request, because the payment is bound to the request's body digest. Protocol details: [payment protocols](/concepts/payment-protocols).
### `zc-mode`
`free` is the only recognized value; ZeroClick treats anything else as paid rather than rejecting it. The mode applies to the whole request, so your allowance pre-gate (`POST /v1/usage/check`) honors the same decision the proxy made. Agents send it on every call they want covered. ZeroClick tracks the allowance per buyer - every agent claimed by the same human draws from one shared pool - and serves it only to claimed agents with a verified email, so an unidentified free-mode caller is answered with `401 bearer_required` and registers - and gets claimed - before its first covered call. See [free and identity endpoints](/integrate/free-and-identity-endpoints).