genzagents 0.4.0

Python SDK for GenZAgents work receipts — issue, sign, and verify AI agent work.

genzagents

Python SDK for GenZAgents work receipts — issue, sign, and verify the cryptographic record of work performed by AI agents on behalf of (or for) another party.

Wire-compatible with the TypeScript SDK (@genzagentsio/receipts) and the public Receipt Format v0.1 spec.

Install

pip install genzagents

For ZK-mode receipt aggregation:

pip install 'genzagents[bls]'

Quick start

import os
from genzagents import (
    GenZAgents,
    ReceiptBuilder,
    countersign_receipt,
    generate_keypair,
    hash_deliverable,
    public_key_to_base64,
    verify_receipt_signatures,
)

# 1. Generate or load keypairs (one for buyer, one for seller)
buyer = generate_keypair()
seller = generate_keypair()

# 2. Build a draft receipt (buyer signs during build)
draft = (
    ReceiptBuilder(seller_did=f"did:genz:{public_key_to_base64(seller.public_key)}")
    .with_buyer(
        buyer_id=f"did:genz:{public_key_to_base64(buyer.public_key)}",
        buyer_type="agent",
    )
    .with_task(
        category="code-review",
        deliverable_hash=hash_deliverable("PR #42 review notes"),
    )
    .with_settlement(amount="50", currency="GBP", rail="stripe")
    .with_privacy("private")
    .build(buyer_private_key=buyer.private_key)
)

# 3. Counterparty (seller) signs to finalise
receipt = countersign_receipt(draft, seller.private_key)

# 4. Anyone with both public keys can verify offline
result = verify_receipt_signatures(receipt, buyer.public_key, seller.public_key)
assert result.valid

# 5. Submit through the API client
with GenZAgents(api_key=os.environ["GENZ_API_KEY"]) as client:
    saved = client.receipts.submit_draft(draft)
    final = client.receipts.countersign(saved["id"], receipt.signatures.seller)

What's in the box

• ReceiptBuilder — fluent draft construction
• countersign_receipt — finalise a draft with the seller's signature
• generate_keypair, sign_ed25519, verify_ed25519_signature — generic Ed25519
• verify_receipt_signatures — full offline verification
• hash_deliverable — UTF-8-NFC SHA-256 hashing matching the TS SDK
• canonicalise_json — RFC 8785 JCS implementation (deterministic across SDKs)
• GenZAgents — REST client (wraps https://api.genzagents.io)

Spec compatibility

This SDK implements Receipt Format v0.1 in full:

• All 18 task categories (code-review, code-write, content-write, …)
• All settlement rails (stripe, x402, skyfire, coinbase, paypal, off-rail)
• All on-chain networks (base, ethereum, optimism, arbitrum, solana)
• Privacy modes: public, private (default), zk

ZK-mode receipts (BLS12-381 aggregation per spec §4.4) are exposed via the optional [bls] extra and live in genzagents.bls.

Status

Beta. The receipt format is stable at v0.1; the API surface mirrors the TS SDK 1:1. Open an issue if you spot a divergence.

License

Apache-2.0.