Python SDK

Official Python client library for Zero Proof AI verification API.

Installation

Terminal
pip install zeroproof

Requires Python 3.8 or higher. The SDK has minimal dependencies (only requests).

Quick Start

from zeroproof import ZeroProof

# Initialize the client
client = ZeroProof(api_key="zkp_your_api_key_here")

# Create a verification challenge
challenge = client.create_challenge(
    agent_id="shopping-assistant-v1",
    action="add_to_cart",
    context={"item_id": "laptop-123", "price": 999.99}
)

print(f"Challenge ID: {challenge.challenge_id}")
print(f"Nonce: {challenge.nonce}")

# Verify the proof
result = client.verify_proof(
    challenge_id=challenge.challenge_id,
    proof="your_cryptographic_proof_here"
)

if result.verified:
    print(f"✅ Verified with {result.confidence * 100}% confidence")
    # Execute the protected action
else:
    print("❌ Verification failed")

Key Features

Simple API

Just 3 core methods: create_challenge, verify_proof, and get_status.

Type Safe

Full type hints and dataclasses for IDE autocomplete and error checking.

Context Manager

Automatic resource cleanup with Python's context manager protocol.

Error Handling

Comprehensive error handling with detailed error messages and status codes.

API Reference

ZeroProof

Main client class for interacting with the API.

__init__(api_key: str, base_url: Optional[str] = None)

Initialize the ZeroProof client.

Parameters:
  • api_key (str) - Your API key (starts with 'zkp_')
  • base_url (str, optional) - Custom API endpoint
Raises:
  • ValueError - If API key is invalid or missing
create_challenge(agent_id: str, action: str, context: Optional[Dict] = None) → Challenge

Create a new verification challenge.

Parameters:
  • agent_id (str) - Unique identifier for the AI agent
  • action (str) - Action to perform (e.g., "add_to_cart")
  • context (dict, optional) - Additional context data
Returns:
  • Challenge - Challenge object with ID, nonce, and expiration
verify_proof(challenge_id: str, proof: str, agent_signature: Optional[str] = None) → VerificationResult

Verify a proof for a given challenge.

Parameters:
  • challenge_id (str) - Challenge ID from create_challenge()
  • proof (str) - Cryptographic proof data
  • agent_signature (str, optional) - Additional signature
Returns:
  • VerificationResult - Result with verified status and confidence
get_status(session_id: str) → Dict[str, Any]

Get the status of a verification session.

Parameters:
  • session_id (str) - Session or challenge ID to check
Returns:
  • dict - Session status with verification details

Data Classes

Challenge

Represents a verification challenge.

challenge_id (str) - Unique identifier
nonce (str) - Random nonce for this challenge
expires_in (int) - Time until expiration (seconds)
timestamp (int) - Challenge creation timestamp
VerificationResult

Represents the result of proof verification.

verified (bool) - Whether proof was verified
agent_id (str) - The verified agent
action (str) - The authorized action
confidence (float) - Confidence score (0.0 to 1.0)
timestamp (str) - Verification timestamp
session_id (str) - Session identifier

Error Handling

from zeroproof import ZeroProof, ZeroProofError

client = ZeroProof(api_key="zkp_...")

try:
    challenge = client.create_challenge("agent", "action")
    result = client.verify_proof(challenge.challenge_id, "proof")
except ZeroProofError as e:
    print(f"Error: {e.message}")
    print(f"Status Code: {e.status_code}")
    print(f"Response: {e.response}")

Context Manager Support

The SDK supports Python's context manager protocol for automatic resource cleanup:

with ZeroProof(api_key="zkp_...") as client:
    challenge = client.create_challenge("agent-1", "purchase")
    result = client.verify_proof(challenge.challenge_id, proof)
    # Session automatically closed when exiting context

See it in action

Check out complete examples including shopping agents, payment processing, and more.

View Examples