skalor-sdk 0.6.0

Python SDK for SKALOR — the Fiduciary Clearing House for AI Agents. Dual-protocol: MPP (Tempo/PathUSD) + x402 (Base L2/USDC).

skalor-sdk

Fiduciary Control Plane for AI Agents — Python SDK

SKALOR lets AI developers wrap every paid API call with a fiduciary authorization check. Before your agent spends money at OpenAI, X.com, or any vendor, the control plane validates spending limits, kill switches, and shadow mandates.

Install

pip install skalor-sdk

Or install from source:

cd sdk
pip install -e .

Quick Start

from skalor import Client, SkalorPaymentError

# Initialize with your API key (from dashboard → API Keys)
zc = Client(api_key="sk_live_abc123...")

# Before calling a paid API, authorize the spend
try:
    approval = zc.authorize_spend(
        amount=0.03,          # USD
        merchant="OpenAI",    # Who you're paying
        memo="GPT-4 call",   # Optional audit trail
    )
    print(f"Approved! tx={approval.transaction_id}")
    print(f"Remaining budget: ${approval.remaining_daily_limit}")

    # Now safe to call OpenAI
    # response = openai.chat.completions.create(...)

except SkalorPaymentError as e:
    # Control plane said NO — don't make the call
    print(f"Blocked: {e.reason}")
    # e.reason is one of: AGENT_INACTIVE, EXCEEDS_DAILY_LIMIT, etc.

How It Works

Your Agent                SKALOR                  Vendor API
    │                         │                           │
    ├─ authorize_spend() ────►│                           │
    │                         ├─ Check kill switch        │
    │                         ├─ Check per-tx limit       │
    │                         ├─ Check daily limit        │
    │                         ├─ Settle on Solana         │
    │◄── ApprovalResult ──────┤                           │
    │                         │                           │
    ├─ (if approved) call ───────────────────────────────►│
    │◄── response ────────────────────────────────────────┤

Exceptions

Exception	Status	When
SkalorPaymentError	402/403	Spend denied (over limit, inactive agent)
SkalorAuthError	401	Invalid API key
SkalorRateLimitError	429	Too many requests
SkalorNetworkError	—	API unreachable

Denial Reasons

When SkalorPaymentError is raised, check e.reason:

• AGENT_INACTIVE — Kill switch is off
• AGENT_PAUSED / AGENT_SUSPENDED / AGENT_REVOKED
• EXCEEDS_PER_TX_LIMIT — Single transaction too large
• EXCEEDS_DAILY_LIMIT — Daily budget exhausted
• INSUFFICIENT_TREASURY — Not enough funds in treasury
• MERCHANT_NOT_AUTHORIZED — Vendor not on allowlist

Configuration

# Custom endpoint (self-hosted or dev)
zc = Client(
    api_key="sk_live_abc123...",
    base_url="http://localhost:8081",
    timeout=10.0,
)

# Context manager
with Client(api_key="sk_live_abc123...") as zc:
    result = zc.authorize_spend(amount=1.00, merchant="Helius")

License

MIT