Metadata-Version: 2.4
Name: valta-python-sdk
Version: 0.1.0
Summary: Official Python SDK for Valta AI agent financial infrastructure.
Author: Valta
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: responses>=0.25.0; extra == "dev"

# valta-python-sdk

Official Python SDK for [Valta](https://valta.co), AI agent financial infrastructure.

Give your AI agents their own wallets, spending policies, kill switches, and audit logs.

```bash
pip install valta-python-sdk
```

---

## Quick Start

```python
from valta import ValtaClient

valta = ValtaClient("sk_valta_live_your_api_key")

agent = valta.agents.create({
    "name": "Portfolio Watcher",
    "description": "Tracks portfolio activity",
    "wallet": {
        "initialBalance": 0,
        "dailyLimit": 500,
    },
})

valta.policies.create({
    "agentId": agent["id"],
    "dailyLimit": 500,
    "monthlyLimit": 5000,
    "maxPerTransaction": 100,
    "requireApprovalAbove": 250,
})

wallet = valta.wallets.get(agent["id"])
print(wallet["balance"])

valta.agents.freeze(agent["id"])

logs = valta.audit.list({"agentId": agent["id"], "limit": 50})
```

---

## Get an API Key

1. Go to [valta.co/dashboard](https://valta.co/dashboard)
2. Navigate to API Keys
3. Create a new key

You can also log in from Python and let the client store the returned key.

```python
from valta import ValtaClient

valta = ValtaClient()
session = valta.auth.login("you@example.com", "your-password")
print(session["token"])
```

---

## Agents

```python
agents = valta.agents.list({"page": 1, "limit": 20, "status": "active"})

agent = valta.agents.get("ag_abc123")

agent = valta.agents.create({
    "name": "Treasury Monitor",
    "description": "Monitors spend and liquidity",
})

agent = valta.agents.update("ag_abc123", {
    "name": "Treasury Monitor",
    "description": "Updated instructions",
})

valta.agents.freeze("ag_abc123")
valta.agents.unfreeze("ag_abc123")

run = valta.agents.run("ag_abc123", {
    "task": "Review today spending",
    "context": "USDC treasury account",
})

run = valta.agents.getRun("ag_abc123", "run_abc123")
runs = valta.agents.listRuns("ag_abc123", {"limit": 10, "status": "completed"})

valta.agents.delete("ag_abc123")
```

---

## Wallets

```python
wallet = valta.wallets.get("ag_abc123")
balance = valta.wallets.getBalance("ag_abc123")

deposit = valta.wallets.getDepositAddress("ag_abc123")

transactions = valta.wallets.listTransactions("ag_abc123", {
    "limit": 20,
    "type": "transfer",
})

transfer = valta.wallets.transfer({
    "fromAgentId": "ag_abc123",
    "toAgentId": "ag_def456",
    "amount": 100,
    "description": "Fund allocation",
})
```

---

## Policies

```python
policy = valta.policies.create({
    "agentId": "ag_abc123",
    "dailyLimit": 200,
    "monthlyLimit": 2000,
    "maxPerTransaction": 50,
    "requireApprovalAbove": 100,
    "blockedCategories": ["gambling"],
    "allowedDomains": ["valta.co"],
    "blockedDomains": ["example.com"],
})

policy = valta.policies.get("ag_abc123")

policy = valta.policies.update("ag_abc123", {
    "dailyLimit": 500,
    "maxPerTransaction": 100,
})

valta.policies.delete("ag_abc123")
```

---

## Audit Trail

```python
logs = valta.audit.list({
    "agentId": "ag_abc123",
    "from": "2026-01-01",
    "to": "2026-01-31",
    "page": 1,
    "limit": 50,
})

entry = valta.audit.get("log_abc123")

all_entries = valta.audit.export({"agentId": "ag_abc123"})
verification = valta.audit.verify("ag_abc123")
print(verification["intact"])
```

---

## API Keys

```python
keys = valta.keys.list()

created = valta.keys.create({"name": "production"})
print(created["fullKey"])

valta.keys.revoke("key_abc123")
```

---

## Sandbox

Sandbox mode is available with test API keys. Sandbox data is isolated from live data.

```python
valta = ValtaClient("sk_valta_test_your_api_key")

deposit = valta.sandbox.deposit({
    "amount": 1000,
    "agent": "ag_abc123",
    "idempotencyKey": "deposit-1",
})

result = valta.spend({
    "agent": "ag_abc123",
    "amount": 50,
    "merchant": "Test API",
    "category": "tools",
    "purpose": "Sandbox purchase",
})

valta.sandbox.reset()
```

---

## Configuration

```python
valta = ValtaClient({
    "apiKey": "sk_valta_live_your_api_key",
    "baseUrl": "https://www.valta.co/api/v1",
})
```

The SDK sends `Content-Type: application/json`, `X-Valta-SDK: 2.3.0`, and `x-api-key` headers on authenticated requests.

---

## Error Handling

```python
from valta import AuthError, RateLimitError, TierError, ValtaClient

valta = ValtaClient("sk_valta_live_your_api_key")

try:
    valta.agents.create({"name": "Agent"})
except TierError as err:
    print(f"Upgrade required: {err.requiredTier}")
    print(f"Upgrade at: {err.upgradeUrl}")
except AuthError:
    print("Invalid API key")
except RateLimitError:
    print("Slow down, rate limit hit")
```

| Error | Status | When |
|---|---:|---|
| `AuthError` | 401 | Invalid or missing API key |
| `TierError` | 403 | Feature requires a higher tier |
| `RateLimitError` | 429 | Too many requests |
| `NotFoundError` | 404 | Agent or resource not found |
| `ValtaError` | 5xx | Server error |

---

## License

MIT, built by [Valta](https://valta.co)
