Python SDK quickstart

The zeroclick-sellers package implements the ZeroClick billing guard for Python backends: it verifies that each request came from ZeroClick, checks the buyer’s allowance before you do the work, returns the refusal responses ZeroClick expects, and settles or reports what was used. This page wires the guard into FastAPI, Flask, and Django. The integration overview describes the contract it implements.

Install

pip install zeroclick-sellers

The package requires Python 3.10 or later and is fully typed (it ships py.typed, so type checkers see every signature). Its HTTP calls go through httpx.

You need three values from the dashboard: your signing secret (zcsec_…), its key id (hsec_…), and an API key (zc_…) with the usage:read and usage:write scopes. See keys and secrets.

ZEROCLICK_SIGNING_SECRET_KID=hsec_k5nq0v7m3d8p
ZEROCLICK_SIGNING_SECRET=zcsec_…
ZEROCLICK_API_KEY=zc_…

Pick the right client

Your framework	Client	Guard call
FastAPI, Starlette (ASGI)	`create_async_seller`	`await zeroclick.guard(...)`
Flask, Django (WSGI)	`create_seller`	`zeroclick.guard(...)`

Use the async client in ASGI apps. The blocking client would stall the event loop during every allowance check. The two clients accept the same options and make the same decisions; they differ only in how they perform IO.

Guard a FastAPI route

import os
from fastapi import FastAPI, Request
from fastapi.responses import Response

from zeroclick_sellers import SyncUsageItem, UsageItem, ZcResponse, create_async_seller
from zeroclick_sellers.adapters import zc_request_from_asgi_scope

zeroclick = create_async_seller(
    signing_secrets={
        os.environ["ZEROCLICK_SIGNING_SECRET_KID"]: os.environ[
            "ZEROCLICK_SIGNING_SECRET"
        ]
    },
    api_key=os.environ["ZEROCLICK_API_KEY"],
)
app = FastAPI()


def to_fastapi(response: ZcResponse) -> Response:
    return Response(
        content=response.body,
        status_code=response.status,
        headers=dict(response.headers),
    )


@app.post("/v1/product-watch")
async def product_watch(request: Request) -> Response:
    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)

    result = do_the_work(owner=decision.context.zc_agent_id)

    return to_fastapi(
        zeroclick.with_usage(
            ZcResponse.json(result),
            [
                SyncUsageItem(
                    service_slug="product-watch", meter_slug="requests", quantity=1
                )
            ],
        )
    )

The handler is four moves:

Adapt. zc_request_from_asgi_scope turns the framework request into a ZcRequest built from the raw path and raw body bytes.
Guard. guard verifies the zc-signature header before it calls the allowance API, and returns a decision, not an exception.
Deny. A deny decision carries the exact response to return: 401 for a bad signature, the 402 payment_required body ZeroClick converts into a payment challenge, or 503 under a fail-closed outage policy. An allow decision carries the verified context: decision.context.zc_agent_id identifies the buyer.
Settle. with_usage stamps the zc-usage response header with the actual usage. ZeroClick records that usage and strips the header before the agent sees the response.

Flask and Django

The handler keeps the same shape: create_seller, no await, and the WSGI adapter in place of the ASGI one.

import os
from flask import Flask, Response, request

from zeroclick_sellers import SyncUsageItem, UsageItem, ZcResponse, create_seller
from zeroclick_sellers.adapters import zc_request_from_wsgi_environ

zeroclick = create_seller(
    signing_secrets={
        os.environ["ZEROCLICK_SIGNING_SECRET_KID"]: os.environ[
            "ZEROCLICK_SIGNING_SECRET"
        ]
    },
    api_key=os.environ["ZEROCLICK_API_KEY"],
)
app = Flask(__name__)


def to_flask(response: ZcResponse) -> Response:
    return Response(
        response=response.body,
        status=response.status,
        headers=dict(response.headers),
    )


@app.post("/v1/product-watch")
def product_watch() -> Response:
    # request.get_data() returns the raw body without consuming it for later
    # handlers; never use request.json here, which would re-serialise.
    zc_request = zc_request_from_wsgi_environ(request.environ, request.get_data())

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

    result = do_the_work(owner=decision.context.zc_agent_id)

    return to_flask(
        zeroclick.with_usage(
            ZcResponse.json(result),
            [
                SyncUsageItem(
                    service_slug="product-watch", meter_slug="requests", quantity=1
                )
            ],
        )
    )

import os
from django.http import HttpRequest, HttpResponse
from django.urls import path

from zeroclick_sellers import SyncUsageItem, UsageItem, ZcResponse, create_seller
from zeroclick_sellers.adapters import zc_request_from_wsgi_environ

zeroclick = create_seller(
    signing_secrets={
        os.environ["ZEROCLICK_SIGNING_SECRET_KID"]: os.environ[
            "ZEROCLICK_SIGNING_SECRET"
        ]
    },
    api_key=os.environ["ZEROCLICK_API_KEY"],
)


def to_django(response: ZcResponse) -> HttpResponse:
    django_response = HttpResponse(
        content=response.body,
        status=response.status,
        content_type=response.headers.get("content-type", "application/json"),
    )
    for key, value in response.headers.items():
        if key.lower() != "content-type":
            django_response[key] = value
    return django_response


def product_watch(request: HttpRequest) -> HttpResponse:
    # request.body is the raw bytes. request.META is the WSGI environ, which
    # is where the raw target lives; request.path is already decoded.
    zc_request = zc_request_from_wsgi_environ(request.META, request.body)

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

    result = do_the_work(owner=decision.context.zc_agent_id)

    return to_django(
        zeroclick.with_usage(
            ZcResponse.json(result),
            [
                SyncUsageItem(
                    service_slug="product-watch", meter_slug="requests", quantity=1
                )
            ],
        )
    )


urlpatterns = [path("v1/product-watch", product_watch)]

Why the adapters exist

The signature covers the request target exactly as ZeroClick sent it, so ZcRequest.path_and_query must be the raw, percent-encoded path and query. Every framework hands you a decoded one. These are the observed values for GET /v1/items/a%2Fb%20c:

	Decoded (unusable)	Raw (correct)
ASGI / uvicorn	`scope["path"]` → `/v1/items/a/b c`	`scope["raw_path"]` → `/v1/items/a%2Fb%20c`
WSGI / werkzeug	`PATH_INFO` → `/v1/items/a/b c`	`RAW_URI` → `/v1/items/a%2Fb%20c?…`

Using the decoded path produces a different canonical string and fails verification. The adapters handle this. They also cover a spec difference between the two interfaces: ASGI’s raw_path excludes the query string (the adapter appends scope["query_string"]), while WSGI’s RAW_URI and REQUEST_URI already include it. The body has the same rule: pass the raw bytes exactly as received, before any framework parses or re-serializes them. Use await request.body() in FastAPI, request.get_data() in Flask, and request.body in Django.

On WSGI, if the server sets neither RAW_URI nor REQUEST_URI, the SDK cannot recover an encoded separator. WSGI decodes %2F to / before the SDK runs, and nothing can tell it from a literal /. gunicorn, werkzeug, uWSGI, and nginx all set one of them.

Test the guard

The guard must deny a plain request with no ZeroClick headers. Only signed requests from ZeroClick reach your handler:

curl -i -X POST http://localhost:8000/v1/product-watch
# HTTP/1.1 401
# {"error":"invalid_zeroclick_signature"}

The quickstart covers the rest of the loop: deploying the guarded route and running the dashboard’s API setup verification against it.

Next steps

Configuration

Every constructor option: secrets, split usage keys, outage policy, timeouts.

API reference

Every public export, from guard to the encryption helpers.

Errors

Decisions versus exceptions, and every ZCError code.

Charge up to a maximum

Bill work you cannot size up front, like output tokens.

Overview

TypeScript

Python

Go

Python SDK quickstart

Install

Pick the right client

Guard a FastAPI route

Flask and Django

Why the adapters exist

Test the guard

Next steps

Configuration

API reference

Errors

Charge up to a maximum

​Install

​Pick the right client

​Guard a FastAPI route

​Flask and Django

​Why the adapters exist

​Test the guard

​Next steps

Configuration

API reference

Errors

Charge up to a maximum

Install

Pick the right client

Guard a FastAPI route

Flask and Django

Why the adapters exist

Test the guard

Next steps