Go SDK middleware

The Go SDK packages the whole guard flow (verify, check allowance, serve, settle) as net/http middleware. Meter guards a billable endpoint; Identify guards a free endpoint that must still know which buyer is calling. Both return a plain func(http.Handler) http.Handler, the standard middleware shape, so they compose with net/http, chi, gorilla/mux, and anything else built on http.Handler.

// Billable: one fixed charge per request.
mux.Handle("/v1/product-watch", seller.Meter(sellers.PerRequest("requests", 1))(
	http.HandlerFunc(productWatch)))

// Free, but identity-scoped: the caller must prove which buyer they are.
mux.Handle("/v1/limits", seller.Identify()(http.HandlerFunc(limits)))

Meter needs ServiceSlug set on the client’s Config; it reads the service, plan, and body limit from there.

What Meter does on every request

In order: it reads the request body under the configured cap, verifies the zc-signature header over the raw bytes, and checks the buyer’s allowance for the declared usage. Only then does it call your handler, with the body restored and the buyer in the request context. When your handler responds 2xx, it attaches the zc-usage header so the request settles.

Behavior	Why it matters
Restores `r.Body` after verification	The signature covers the raw bytes, so verifying consumes the body. Without this, your handler reads empty, and does so silently.
`zc-usage` only on a 2xx	A 4xx is the buyer’s bad input and a 5xx is your failure. Neither should bill.
Bounds the body (`MaxBodyBytes`, default 10 MiB)	Verification needs the whole body in memory, and an attacker does not need a valid signature to make you buffer it. Over the cap, the middleware refuses the request with `413 {"error":"request_body_too_large"}` before verification.
Puts the buyer in the request context	`sellers.FromContext(r.Context())` returns the verified `AgentID` and `RequestID`.
Refuses before your handler runs	The middleware refuses an unsigned request before it ever consults the allowance API, and refuses an unpayable one before your code runs. Unpayable traffic never costs you work.

A refusal is the exact response ZeroClick expects: 401 {"error":"invalid_zeroclick_signature"} for a failed verification, the priced 402 payment_required body for an allowance denial, or 503 {"error":"allowance_unavailable"} under a fail-closed outage policy. See integrate your API for the bodies and when each one is returned.

Fixed quantities only

Meter settles exactly what it declares, so it takes fixed quantities only: sellers.PerRequest(meter, n) items. If handed an UpTo item or a non-positive quantity, it panics at wire-up. A ceiling has no settled quantity: it would bill zero, silently, on a delivered 200, which is the exact failure this SDK exists to prevent. The panic happens when you build the middleware, not in production traffic. For work you cannot size up front, declare the fixed part to Meter and report the variable part after responding.

Billing for work you can’t size up front

Declare a fixed charge to the guard: that is what lets ZeroClick offer the exact payment scheme, which is the one clients can pay today. Then report the variable part with ReportUsage after the response has gone out. This example charges one requests unit per call synchronously and reports output_tokens afterwards:

handler := func(w http.ResponseWriter, r *http.Request) {
	zc, _ := sellers.FromContext(r.Context())

	tokens := 1842 // discovered by doing the work

	w.WriteHeader(http.StatusOK)
	fmt.Fprintf(w, `{"outputTokens":%d}`, tokens)

	// Reported AFTER the response. Two things matter here:
	//
	//  1. BackgroundContext, not r.Context(): the request context is
	//     already cancelled, so the report would be silently dropped and
	//     the tokens would go unbilled.
	//  2. An idempotency key derived from the request id, never random:
	//     a retried report with a fresh key double-bills.
	_, err := seller.ReportUsage(sellers.BackgroundContext(r), sellers.ReportUsageInput{
		AgentID:        zc.AgentID,
		ServiceSlug:    "product-watch",
		MeterSlug:      "output_tokens",
		Quantity:       tokens,
		IdempotencyKey: zc.RequestID + "_output_tokens",
	})
	if err != nil {
		// Delivered but unbilled. Log it; do not fail a request the
		// buyer already has.
		log.Printf("output_tokens not reported: %v", err)
	}
}

http.Handle("/v1/product-watch", seller.Meter(sellers.PerRequest("requests", 1))(
	http.HandlerFunc(handler)))

Two things are easy to get wrong:

Use sellers.BackgroundContext(r), not r.Context(). The server cancels the request context the moment your handler returns, so a report on it is dropped and the work goes unbilled with nothing in the logs.

Derive the idempotency key: zc.RequestID + "_output_tokens", never a random value. A random key double-bills on retry; a derived key makes the retry a harmless duplicate.

To let the buyer authorize a variable amount up front instead, see charge up to a maximum. That pattern uses Guard directly rather than Meter.

Settling on 2xx only

The middleware wraps your response writer and defers the zc-usage header until the status is known, because only a delivered response should be billed. A 4xx means you rejected the buyer’s input, and a 5xx is your own failure. Charging for either bills someone for work they did not receive. Two edge cases the wrapper handles for you:

A handler that writes nothing still delivers a 200 (net/http emits it at the transport layer, below the wrapper), so the middleware settles it explicitly rather than letting the work ship unbilled.
A handler that sets its own zc-usage header wins: the middleware attaches the declared usage only when the header is not already present, so you can override the settled quantities for one response when you must.

Streaming and WebSockets

The wrapped writer implements http.Flusher, http.Hijacker, and Unwrap (for http.ResponseController), so streaming handlers work unchanged:

Server-sent events: a direct w.(http.Flusher) assertion, the long-standing streaming idiom, succeeds. Flush settles the usage header before the first byte leaves, because headers cannot follow the body.
WebSocket upgrades: Hijack works, but a hijacked connection leaves HTTP response semantics behind, so no zc-usage header can follow it. Meter the connection itself as the fixed charge and report anything per-message with ReportUsage.

Identify

Identify guards a free endpoint that must still know which buyer is calling, such as a limits or account route. It bounds and restores the body and verifies the signature exactly as Meter does, but makes no network call and settles nothing. A signed request with no zc-agent-id header is an anonymous probe: valid, but it has not established a buyer. Identify answers it with a 402 carrying an empty usage list. That makes ZeroClick issue a $0 identity challenge and retry the request with the identity attached. Your handler then finds the buyer with sellers.FromContext:

func limits(w http.ResponseWriter, r *http.Request) {
	zc, _ := sellers.FromContext(r.Context())
	w.Header().Set("content-type", "application/json")
	json.NewEncoder(w).Encode(map[string]any{"zcAgentId": zc.AgentID})
}

See free and identity endpoints for when to use this over an unguarded route.

Failure modes

Condition	Response
Body exceeds `MaxBodyBytes`, or the client hung up mid-body	`413 {"error":"request_body_too_large"}`. The SDK cannot verify a signature over a body the server does not fully have.
Signature missing, malformed, stale, or wrong	`401 {"error":"invalid_zeroclick_signature"}`
Allowance denied	The priced `402 payment_required` body.
Allowance API unreachable	Governed by `Policy`: served (default), `503 {"error":"allowance_unavailable"}`, or treated as an error.
Guard returned an error: a malformed usage list, a signing-secret resolver fault, or `PolicyThrow` surfacing an outage	`500 {"error":"internal_error"}`, with the underlying error written to the configured `Logger`. Neither is the buyer’s fault, and neither bills.

The full split between decisions and errors is on the errors page.

Deploying behind a proxy

The signature covers the raw, percent-encoded request target. The SDK reads r.RequestURI, which Go leaves untouched. But a reverse proxy, ingress, or load balancer in front of you may normalize the path (%2F becoming /) before your server sees it. If that happens, every request with an encoded path segment fails verification. If you route through nginx, an ingress controller, or a managed load balancer, confirm it passes the request target through unmodified.

The signature spec specifies the exact bytes the signature covers.

Overview

TypeScript

Python

Go

What Meter does on every request

Fixed quantities only

Billing for work you can’t size up front

Settling on 2xx only

Streaming and WebSockets

Identify

Failure modes

Deploying behind a proxy

​What Meter does on every request

​Fixed quantities only

​Billing for work you can’t size up front

​Settling on 2xx only

​Streaming and WebSockets

​Identify

​Failure modes

​Deploying behind a proxy

What Meter does on every request

Fixed quantities only

Billing for work you can’t size up front

Settling on 2xx only

Streaming and WebSockets

Identify

Failure modes

Deploying behind a proxy