Integration overview

Agents buy and pay at your pay URL (https://acme.pay.zeroclick.io). ZeroClick verifies the payment, signs the request, and forwards it to your API at your configured upstream base URL. This page is the whole contract between ZeroClick and your backend. The seller SDKs implement it; the REST walkthrough shows how to implement it without one.

What arrives on every forwarded request

ZeroClick sets three headers on each request it forwards:

Header	Value	Purpose
`zc-request-id`	`zcreq_8h2m4x0q9k1f`	Correlation id. The same id flows through the probe, the challenge, the paid retry, the allowance check, and the usage record.
`zc-agent-id`	`agt_x7f2kq93bh0d`	The buyer. Absent or empty on signed anonymous probes, which are valid. See verify requests.
`zc-signature`	`t=<unix seconds>,kid=hsec_…,v1=<64 hex>`	HMAC-SHA256 proof that the request came through ZeroClick unmodified. Sandbox traffic appends `,sb=1` and adds a `zc-sandbox: 1` header.

Before forwarding, ZeroClick strips all inbound zc-*, x-payment, and payment* headers and sets its own, so a caller can never inject them. Other request headers pass through untouched. Your API’s own authentication remains whatever you configured between yourself and ZeroClick. One more header matters to the contract without ever reaching you: zc-mode. A buyer sends zc-mode: free to the pay URL to opt a call into included-units coverage. ZeroClick consumes it there, and a missing or unrecognized value means paid. See free and identity endpoints. The full header reference is at headers.

The four obligations

On every forwarded request, your backend must:

Verify the zc-signature against your signing secret, before anything else. Only ZeroClick-signed traffic reaches your handlers. See verify requests.
Check the allowance with POST /v1/usage/check: does the buyer’s plan cover what this request will use? See check allowances.
Serve the request as your API normally would.
Settle what the request used: a zc-usage header on the successful response, or an asynchronous usage report. See settle usage.

With an SDK, the first two obligations are one guard call and the fourth is one helper:

const decision = await zeroClick.guard(request, {
  serviceSlug: "product-watch",
  usage: [{ meterSlug: "requests", quantity: 1 }],
});
if (decision.action === "deny") return decision.response;

const response = Response.json({ watching: true });
return zeroClick.withUsage(response, [
  { serviceSlug: "product-watch", meterSlug: "requests", quantity: 1 },
]);

zc_request = zc_request_from_asgi_scope(request.scope, await request.body())

decision = await zeroclick.guard(
    zc_request,
    service_slug="product-watch",
    usage=[UsageItem(meter_slug="requests", quantity=1)],
)
if decision.action == "deny":
    return to_fastapi(decision.response)

return to_fastapi(
    zeroclick.with_usage(
        ZcResponse.json({"watching": True}),
        [SyncUsageItem(service_slug="product-watch", meter_slug="requests", quantity=1)],
    )
)

// Meter verifies the signature, checks the allowance, refuses before the
// handler runs, and settles the zc-usage header on a delivered 2xx.
mux.Handle("/v1/product-watch", seller.Meter(sellers.PerRequest("requests", 1))(
	http.HandlerFunc(productWatch)))

The three refusals

When your API cannot serve, it must answer ZeroClick with one of exactly three responses. The SDKs build all of them. A deny decision carries the response ready to return.

Status	When	Exact body
`401`	The signature is missing, malformed, stale, or invalid.	`{"error":"invalid_zeroclick_signature"}`
`402`	The allowance check denies, or an unpaid request needs payment.	`{"error":"payment_required","serviceSlug":"product-watch","usage":[{"meterSlug":"requests","quantity":1}]}`
`503`	The allowance API is unreachable and your outage policy is fail-closed.	`{"error":"allowance_unavailable"}`

The 402 body is not an error page. It is data. ZeroClick reads the usage list, prices it from your catalog, and issues the buyer a signable payment challenge. The buyer never sees your body. A 402 with usage: [] means “free, but identity-scoped”, which ZeroClick answers with a $0 identity challenge. The errors page lists error codes across the platform.

What never to do

Never serve unverified traffic. Your upstream URL is reachable; the signature is the gate. A request with no ZeroClick headers must get the 401, not your handler.
Never bill on a non-2xx. zc-usage belongs on 2xx responses only: a 4xx is the buyer’s bad input and a 5xx is your failure. Neither delivered anything worth charging for.
Never price or cache challenges yourself. Your 402 declares usage quantities, not prices. ZeroClick prices each refusal from your catalog per request and binds each challenge to that exact request. A cached price or replayed challenge cannot settle.

SDK or REST

If your backend is TypeScript, Python, or Go, use the SDK. It implements the contract, including the denial bodies and the signature edge cases:

TypeScript quickstart: @zeroclickai/sellers on npm
Python quickstart: zeroclick-sellers on PyPI
Go quickstart: cdn.zeroclick.io/sdks/sellers-go

Otherwise the contract is small enough to implement over REST: two API calls, one signature check, three fixed response bodies. Start at the REST walkthrough and the byte-level signature spec.

Work through the contract

Keys and secrets

The three runtime keys, scopes, split read/write keys, and rotation.

Verify requests

What verification proves, anonymous probes, and the raw-path rule.

Check allowances

Guard semantics, usage items, denials, and the outage policy.

Settle usage

The zc-usage header and asynchronous usage reports.

Charge up to a maximum

Use ceilings to bill work you can’t size up front.

Free and identity endpoints

Endpoints that cost nothing but must know the buyer.

Get started

Concepts

Integrate your API

Your website

Resources

Integration overview

What arrives on every forwarded request

The four obligations

The three refusals

What never to do

SDK or REST

Work through the contract

Keys and secrets

Verify requests

Check allowances

Settle usage

Charge up to a maximum

Free and identity endpoints

​What arrives on every forwarded request

​The four obligations

​The three refusals

​What never to do

​SDK or REST

​Work through the contract

Keys and secrets

Verify requests

Check allowances

Settle usage

Charge up to a maximum

Free and identity endpoints

What arrives on every forwarded request

The four obligations

The three refusals

What never to do

SDK or REST

Work through the contract