Python SDK¶
Official Python SDK for the Circuit KYC Network API.
Installation¶
Requirements: Python 3.8+
Quick Start¶
from circuit_kyc import CircuitClient
client = CircuitClient(api_key="sk_sandbox_your-key")
result = client.check_eligibility(
email="user@example.com",
phone="+14155551234"
)
if result.eligible:
print(f"KYC Level: {result.kyc_level}")
Configuration¶
from circuit_kyc import CircuitClient
client = CircuitClient(
api_key="sk_sandbox_your-key", # Required
base_url=None, # Auto-detected from key
timeout=30, # Request timeout (seconds)
max_retries=3, # Retry attempts
environment=None, # 'sandbox' or 'production'
)
Error Handling¶
from circuit_kyc import (
CircuitClient,
AuthenticationError,
RateLimitError,
InsufficientCreditsError,
ValidationError,
)
import time
client = CircuitClient(api_key="sk_sandbox_your-key")
try:
result = client.check_eligibility(email="test@example.com")
except AuthenticationError:
print("Invalid API key")
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after}s")
time.sleep(e.retry_after)
except InsufficientCreditsError as e:
print(f"Low balance: {e.current_balance} credits")
except ValidationError as e:
print(f"Validation error: {e.errors}")
API Reference¶
Eligibility¶
result = client.check_eligibility(
email="user@example.com",
phone="+14155551234",
first_name="John",
last_name="Doe",
date_of_birth="1990-01-15",
ssn_last4="1234",
address={
"street": "123 Main St",
"city": "San Francisco",
"state": "CA",
"zip": "94102"
}
)
Risk Assessment¶
risk = client.assess_risk(
subject_id="user-123",
email="user@example.com",
ip_address="203.0.113.42",
transaction_amount=5000.00,
transaction_currency="USD"
)
print(f"Risk Level: {risk.risk_level}") # low, medium, high, critical
print(f"Risk Score: {risk.risk_score}/100")
Credentials¶
# Issue
credential = client.issue_credential(
subject_id="user-123",
claims={"kyc_level": "full"},
expires_in_days=365
)
# Verify
result = client.verify_credential(credential_jwt)
print(f"Valid: {result.valid}")
# Claim from eligibility
credential = client.claim_identity(
subject_id="user-123",
email="user@example.com",
eligibility_request_id=eligibility.request_id
)
Data Ingestion¶
result = client.ingest_data(
records=[
{
"subject_id": "user-123",
"email": "john@example.com",
"kyc_level": "full",
"verified_at": "2024-01-15T10:30:00Z"
}
]
)
print(f"Batch ID: {result.batch_id}")
Billing¶
# Check balance
balance = client.get_credit_balance()
print(f"Available: {balance.available_credits}")
# Get pricing
pricing = client.get_pricing()
Context Manager¶
with CircuitClient(api_key="sk_sandbox_...") as client:
result = client.check_eligibility(email="test@example.com")