chitmark (Python)

Official Python SDK for Chitmark: trust decisions on agent-mediated actions, tuned by business outcomes.

AI agents and multi-account farms drain free tiers, trial credits, and API allowances while looking exactly like your best customers. Chitmark scores each action in under 50 ms and returns allow, challenge, or deny: cheap for one real human, expensive at farm scale. Then your outcomes (conversion, credit burn, chargeback) come back through feedback and tune the next decision.

Requires Python >= 3.10. Fully typed (py.typed), synchronous httpx under the hood.

Try it without a key: run the playground. Live service health: chitmark.com/status.

Install

pip install chitmark
# or
uv add chitmark

Quick start

from chitmark import Chitmark

with Chitmark(api_key="ck_live_...") as client:
    verdict = client.verify(
        action="signup",
        session="sess_9f3a",
        surface="app.acme.com/signup",
        subject={
            "email": "buyer@acmecorp.com",  # hashed client-side before the wire
            "ip": "203.0.113.7",  # truncated to /24 client-side
            "userAgent": "Mozilla/5.0 ...",
        },
    )

# Persist verdict["eventId"] on the account row: feedback joins only on that id.

The three verbs

Golden rule: fail to challenge, never to allow. Timeouts and transport errors return a degraded challenge verdict (never allow, never a raised error on verify); HTTP errors raise ChitmarkApiError with the status attached.

Feedback: the data moat

Attribution is a schema contract, not a fuzzy match: store the eventId from verify on the account row, then report outcomes against that same id. Never a derived or guessed id.

# At signup: persist the join key
verdict = client.verify(action="signup", subject={"email": "a@b.com"})
db.accounts.update(user_id, chitmark_event_id=verdict["eventId"])

# Later, when a label matures:
client.feedback(
    event_id=account.chitmark_event_id,  # the stored join key: never guessed
    outcome="credit_burn",
    value=87.4,  # dollar amount: unit rides along (default "usd")
    observed_at="2026-08-06T04:00:00Z",
)

Exact duplicate feedback bodies derive the same warehouse id, so retrying a connector never double-counts a burned value. unit ships only alongside value: a currency without an amount is wire noise.

Challenges: friction priced per action

When verify returns challenge, issue one, solve the proof locally, and complete it. Proof-of-work difficulty is server-issued (4 by default, up to 6 at higher risk tiers): about 65k hashes, milliseconds for one human's device, real money at farm scale.

import hashlib

issued = client.challenge(event_id=verdict["eventId"], session="sess_9f3a")
instructions = issued["instructions"]

if instructions["type"] == "pow":
    prefix = "0" * instructions["difficulty"]
    nonce = 0
    while True:
        digest = hashlib.sha256(
            f"{issued['challengeId']}:{instructions['seed']}:{nonce}".encode()
        ).hexdigest()
        if digest.startswith(prefix):
            break
        nonce += 1

    client.complete_challenge(
        event_id=verdict["eventId"],
        challenge_id=issued["challengeId"],
        session="sess_9f3a",
        proof={"type": "proof_of_work", "nonce": str(nonce)},
    )
    # Re-verify with context={"challengeId": ...} so the next verdict honors it.

Signed verdict receipts

Every production verdict ships a verdictToken: an ES256 JWT bound to session, origin, and event. Verify it before acting on high-value decisions (install the verdict extra for the crypto dependency):

pip install "chitmark[verdict]"

from chitmark.verify_token import verify_verdict_token

claims = verify_verdict_token(
    verdict["verdictToken"],
    session="sess_9f3a",  # enforce session binding (recommended)
    aud="api.chitmark.com",  # enforce origin binding
)
# claims: {"eventId", "decision", "actorType", "confidence", "jti", "exp", ...}

Rejects expired tokens, unknown keys, bad signatures, and session or origin mismatches with typed error codes.

PII modes

Dependency injection and lifecycle

The client owns its httpx.Client by default and closes it on context exit. Pass your own for connection pooling or tests:

import httpx
from chitmark import Chitmark

pool = httpx.Client(base_url="https://api.chitmark.com", timeout=0.8)
client = Chitmark(api_key="ck_live_...", http_client=pool)

Develop

cd packages/sdk-python
uv sync --extra dev   # or: pip install -e ".[dev]"
pytest
ruff check .

Agent integration

Using Cursor, Claude Code, Codex, or another coding agent? Point it at chitmark.com/SKILL.md, or paste this into your prompt: Integrate Chitmark into my app following https://chitmark.com/SKILL.md.

Resources

• Agent integration skill
• API reference
• Quickstart
• Playground
• GitHub

License

Proprietary: see LICENSE.