TrustFlow Python SDK

Governance-as-a-Service for AI Agent Transactions

Evaluate transaction risk, enforce compliance, and trace decisions — in one API call.

Install

pip install trustflow

Quick Start

from trustflow import TrustFlowClient

client = TrustFlowClient(api_key="tf_live_a1b2c3...")

# Evaluate a transaction
result = client.evaluate(
    amount=349.99,
    category="electronics",
    merchant_id="amazon_bot",
    user_id="user_456",
)

print(result.decision)    # "APPROVED"
print(result.risk_score)  # 32.5
print(result.risk_level)  # "MEDIUM"
print(result.trace_id)    # "tf-a8f3c9b12e04"
print(result.factors)     # 7 risk factors with scores and explanations

Features

• Automatic retry with exponential backoff
• Typed responses — full IDE autocompletion
• Agent Identity — sign requests with Ed25519/JWS/HMAC for verified agent transactions
• Idempotency — pass idempotency_key to prevent duplicate evaluations
• Sandbox mode — use tf_test_ keys for deterministic testing

Agent Identity Verification

For verified agent transactions (Visa Trusted Agent Protocol, Google AP2, x402):

from trustflow import TrustFlowClient, generate_ed25519_keypair, sign_ed25519

client = TrustFlowClient(api_key="tf_live_...")

# One-time: generate a keypair and register the public key with TrustFlow
priv_b64, pub_b64 = generate_ed25519_keypair()
# POST /v1/identity/issuers with pub_b64 to register your issuer

# Per-transaction: sign the canonical payload
identity = sign_ed25519(
    private_key_b64=priv_b64,
    agent_id="my-shopping-agent-v2",
    issuer="my-company.example.com",
    amount=349.99,
    currency="USD",
    merchant_id="amazon_bot",
    user_id="user_456",
)

result = client.evaluate(
    amount=349.99,
    category="electronics",
    merchant_id="amazon_bot",
    user_id="user_456",
    agent_identity=identity,
)

# Verified agents get lower risk scores
print(result.agent_identity)  # {"status": "verified", "scheme": "ed25519", ...}

Configuration

# Custom base URL
client = TrustFlowClient(
    api_key="tf_live_...",
    base_url="https://your-instance.example.com",
    timeout=10.0,
    max_retries=3,
)

API Reference

Full documentation: api.trust-flow.dev/docs

Get Your API Key

curl -X POST https://api.trust-flow.dev/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "Your Name", "email": "you@company.com"}'

Free tier: 100 evaluations/hour, 1,000/day. No credit card required.

License

MIT