Python SDK

The official Python SDK for AutopayOS. Works with Python 3.9+.

Installation

Bash
pip install autopayos

Or with Poetry:

Bash
poetry add autopayos

Quick start

Python
from autopayos import AutopayosClient

client = AutopayosClient(
    base_url="https://api.autopayos.com",
    api_key="ak_live_your_api_key"
)

# Request permission
permission = client.request_permission(
    agent_did="did:key:z6Mk...",
    principal_did="did:key:z6Mp...",
    amount=50.00,
    currency="USD"
)

if permission.allowed:
    print("Intent approved!")

Configuration

Client options

Python
from autopayos import AutopayosClient

client = AutopayosClient(
    base_url="https://api.autopayos.com",
    api_key="ak_live_your_api_key",
    timeout=30,  # Request timeout in seconds
    retries=3,   # Number of retries
)

Environment-based configuration

Python
import os

client = AutopayosClient(
    base_url=os.environ.get("AUTOPAYOS_URL", "https://api.autopayos.com"),
    api_key=os.environ["AUTOPAYOS_API_KEY"]
)

Async client

Python
from autopayos import AsyncAutopayosClient

async def main():
    client = AsyncAutopayosClient(
        base_url="https://api.autopayos.com",
        api_key="ak_live_your_api_key"
    )
    
    permission = await client.request_permission(
        agent_did="did:key:z6Mk...",
        principal_did="did:key:z6Mp...",
        amount=50.00,
        currency="USD"
    )

Core methods

request_permission

Request permission for an agent to make a purchase.

Python
from autopayos.models import PermissionRequest

permission = client.request_permission(
    agent_did="did:key:z6Mk...",
    principal_did="did:key:z6Mp...",
    amount=100.00,
    currency="USD",
    merchant_domain="amazon.com",
    merchant_mcc="5411",
    idempotency_key="unique-key-123"
)

if permission.allowed:
    print(f"Intent VC: {permission.intent_vc}")
else:
    print(f"Denied: {permission.reason_codes}")

verify_cart

Verify a cart against an intent and policy.

Python
verification = client.verify_cart(
    intent_vc=permission.intent_vc,
    cart_vc=merchant_cart_vc,
    hp_proof=None  # Optional HP proof
)

if verification.allowed:
    print(f"Approval token: {verification.approval_token}")
    print(f"Payment rail: {verification.rail_decision['rail']}")
else:
    print(f"Rejected: {verification.reason_codes}")

execute_payment

Execute a payment with an approval token.

Python
payment = client.execute_payment(
    approval_token=verification.approval_token
)

print(f"Payment mandate: {payment.pm_vc}")
print(f"Stripe PI: {payment.rail_response['paymentIntentId']}")

complete_purchase

Complete an entire purchase flow in one call.

Python
result = client.complete_purchase(
    agent_did="did:key:z6MkAgent...",
    principal_did="did:key:z6MkUser...",
    amount=100.00,
    currency="USD",
    merchant_domain="amazon.com",
    cart_vc=merchant_cart_vc
)

print(f"Payment complete: {result.pm_vc}")

Policy management

get_current_policy

Python
policy = client.get_current_policy()
print(f"Amount cap: {policy.rules['spend']['amount_cap']}")

update_policy

Python
client.update_policy(
    policy_id="pol_abc123",
    rules={
        **existing_rules,
        "spend": {
            "amount_cap": 200.00
        }
    }
)

create_policy

Python
from autopayos.models import PolicyV1

policy = client.create_policy(
    name="Shopping Agent Policy",
    rules=PolicyV1(
        version="2.0",
        spend={
            "amount_cap": 100.00,
            "currency": "USD",
            "categories": ["groceries", "electronics"]
        },
        merchant={
            "allow_list": ["amazon.com", "walmart.com"]
        }
    )
)

print(f"Policy ID: {policy.id}")

simulate_policy

Test a policy without creating an intent.

Python
result = client.simulate_policy(
    policy_id="pol_abc123",
    request={
        "amount": 150.00,
        "currency": "USD",
        "merchantDomain": "amazon.com"
    }
)

print(f"Would be allowed: {result.allowed}")
print(f"Violations: {result.reason_codes}")

Agent management

register_agent

Python
agent = client.register_agent(
    name="Shopping Assistant",
    description="AI-powered shopping agent",
    capabilities=["browse", "purchase"],
    public_key=my_public_key
)

print(f"Agent DID: {agent.did}")

get_agent

Python
agent = client.get_agent(agent_did)
print(f"Status: {agent.status}")
print(f"Linked policy: {agent.linked_policy_id}")

get_agents

Python
agents = client.get_agents(
    status="ACTIVE",
    limit=50
)

for agent in agents.data:
    print(f"{agent.display_name}: {agent.did}")

revoke_agent

Python
client.revoke_agent(
    agent_did=agent_did,
    reason="Security concern"
)

Evidence

get_evidence

Python
evidence = client.get_evidence(
    last=50,
    event_types=["PAYMENT_AUTHORIZED"],
    from_date="2025-12-01"
)

print(f"Events: {len(evidence.events)}")
print(f"Chain valid: {evidence.chain_valid}")

for event in evidence.events:
    print(f"{event.event_type} at {event.created_at}")

get_evidence_bundle

Python
bundle = client.get_evidence_bundle(transaction_id)

print(f"Transaction: {bundle.transaction_id}")
print(f"Events: {len(bundle.events)}")

verify_evidence_chain

Python
result = client.verify_evidence_chain(
    from_seq=1000,
    to_seq=1100
)

if not result.valid:
    print(f"Chain broken at: {result.broken_at}")

Demo helpers

demo_cart

Python
cart = client.demo_cart(
    payer_did="did:key:z6MkUser...",
    domain="test-merchant.autopayos.com",
    amount=50.00,
    currency="USD",
    items=[
        {"name": "Test Product", "price": 50.00, "quantity": 1}
    ]
)

demo_hp_proof

For testing only:

Python
hp = client.demo_hp_proof(
    agent_did="did:key:z6Mk...",
    freshness_seconds=300
)

Error handling

AutopayosError

Python
from autopayos.exceptions import AutopayosError

try:
    permission = client.request_permission(...)
except AutopayosError as e:
    print(f"Code: {e.code}")
    print(f"Message: {e.message}")
    print(f"Details: {e.details}")
    
    if e.code == "AMOUNT_OVER_CAP":
        # Handle amount limit
        pass
    elif e.code == "MERCHANT_NOT_ALLOWED":
        # Handle merchant restriction
        pass
    elif e.code == "RATE_LIMITED":
        # Wait and retry
        pass

Specific exceptions

Python
from autopayos.exceptions import (
    AuthenticationError,
    RateLimitError,
    PolicyViolationError,
    NetworkError
)

try:
    permission = client.request_permission(...)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except PolicyViolationError as e:
    print(f"Policy violation: {e.reason_codes}")
except NetworkError:
    print("Network error, please retry")

Models

PermissionResponse

Python
@dataclass
class PermissionResponse:
    allowed: bool
    intent_vc: Optional[Dict] = None
    attestation: Optional[Dict] = None
    reason_codes: Optional[List[str]] = None
    hp_required: Optional[bool] = None
    hp_challenge: Optional[Dict] = None

CartVerificationResponse

Python
@dataclass
class CartVerificationResponse:
    allowed: bool
    approval_token: Optional[str] = None
    approval_token_expires_at: Optional[str] = None
    rail_decision: Optional[Dict] = None
    reason_codes: Optional[List[str]] = None

PaymentExecutionResponse

Python
@dataclass
class PaymentExecutionResponse:
    pm_vc: Dict
    rail_response: Dict

PolicyV1

Python
@dataclass
class PolicyV1:
    version: str = "2.0"
    spend: Optional[Dict] = None
    merchant: Optional[Dict] = None
    context: Optional[Dict] = None
    risk: Optional[Dict] = None
    rails: Optional[Dict] = None

Async support

All methods have async equivalents:

Python
import asyncio
from autopayos import AsyncAutopayosClient

async def main():
    client = AsyncAutopayosClient(
        base_url="https://api.autopayos.com",
        api_key="ak_live_..."
    )
    
    # All methods are async
    permission = await client.request_permission(
        agent_did="did:key:z6Mk...",
        principal_did="did:key:z6Mp...",
        amount=50.00,
        currency="USD"
    )
    
    if permission.allowed:
        cart = await client.demo_cart(
            payer_did="did:key:z6Mp...",
            domain="test.com",
            amount=40.00,
            currency="USD"
        )
        
        verification = await client.verify_cart(
            intent_vc=permission.intent_vc,
            cart_vc=cart.cart_vc
        )
        
        if verification.allowed:
            payment = await client.execute_payment(
                approval_token=verification.approval_token
            )
            print(f"Payment complete: {payment.pm_vc}")

asyncio.run(main())

Context manager

Python
from autopayos import AutopayosClient

with AutopayosClient(
    base_url="https://api.autopayos.com",
    api_key="ak_live_..."
) as client:
    permission = client.request_permission(...)

Or async:

Python
async with AsyncAutopayosClient(...) as client:
    permission = await client.request_permission(...)

Logging

Enable debug logging:

Python
import logging

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("autopayos").setLevel(logging.DEBUG)

Best practices

1. Use environment variables

Python
import os

client = AutopayosClient(
    base_url=os.environ["AUTOPAYOS_URL"],
    api_key=os.environ["AUTOPAYOS_API_KEY"]
)

2. Handle all error cases

Python
permission = client.request_permission(...)

if not permission.allowed:
    for code in permission.reason_codes or []:
        if code == "AMOUNT_OVER_CAP":
            # Reduce amount
            pass
        elif code == "MERCHANT_NOT_ALLOWED":
            # Try different merchant
            pass

3. Use idempotency keys

Python
permission = client.request_permission(
    agent_did="...",
    principal_did="...",
    amount=50.00,
    currency="USD",
    idempotency_key=f"intent-{order_id}-{int(time.time())}"
)

4. Log transaction IDs

Python
payment = client.execute_payment(approval_token=...)
logger.info(
    "Payment complete",
    mandate_id=payment.pm_vc["credentialSubject"]["mandateId"]
)

Next steps