Metadata-Version: 2.4
Name: skalor-sdk
Version: 0.7.0
Summary: Python SDK for SKALOR — the Fiduciary Clearing House for AI Agents. Three-rail settlement: MPP (Tempo/PathUSD) + x402 (Base L2/USDC) + Canton Network.
Author-email: SKALOR <dev@skalor.xyz>
License: MIT
Project-URL: Homepage, https://github.com/josephthompson101/skalor
Project-URL: Documentation, https://github.com/josephthompson101/skalor/tree/main/sdk
Project-URL: Repository, https://github.com/josephthompson101/skalor
Keywords: ai,agents,payments,fiduciary,mcp,tempo,fintech,x402,base,canton,ecdsa,ed25519,three-rail,zero-trust,langchain,crewai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: PyNaCl>=1.5.0

# 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

```bash
pip install skalor-sdk
```

Or install from source:

```bash
cd sdk
pip install -e .
```

## Quick Start

```python
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

```python
# 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
