Metadata-Version: 2.4
Name: aegisprivacy-sdk
Version: 0.1.0
Summary: AEGIS SDK — privacy-routed HTTP requests for AI agents
License: MIT
Project-URL: Homepage, https://aegisprivacy.org
Keywords: vpn,proxy,privacy,ai-agent,x402,solana
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# aegis-sdk

Privacy-routed HTTP requests for AI agents and developers. Route any request through a residential exit node and pay per-request in USDC on Solana.

## Install

```bash
pip install aegis-sdk
```

## Quick start

```python
from aegis import Aegis

aegis = Aegis(api_key="aegis_your_key_here")

# GET — routed through a US residential IP
res = aegis.get("https://httpbin.org/ip")
print(res.json())
# {"origin": "12.34.56.78"}  ← a residential US IP, not yours

# POST with a specific exit country
res = aegis.post(
    "https://api.example.com/data",
    body={"query": "hello"},
    country="JP",
    ip_class="residential",
)
print(res.json())
```

## API

### `Aegis(api_key, *, base_url?, default_country?, default_ip_class?)`

| Param | Default | Description |
|---|---|---|
| `api_key` | required | API key from [aegisprivacy.org/agent](https://aegisprivacy.org/agent) |
| `default_country` | `"US"` | Default exit country |
| `default_ip_class` | `"residential"` | Default IP class |
| `base_url` | production | Override for local dev |

### `aegis.fetch(url, *, method, country, ip_class, headers, body)` → `AegisResponse`

Full request method. All keyword args are optional.

### `aegis.get(url, *, country?, ip_class?, headers?)` → `AegisResponse`

### `aegis.post(url, body, *, country?, ip_class?, headers?)` → `AegisResponse`

### `aegis.balance()` → `dict`

Returns `{"usdc": "1.23"}` — remaining balance for this API key.

### `AegisResponse`

```python
res.status   # int
res.ok       # bool
res.headers  # dict
res.text()   # str
res.json()   # any
```

## Errors

```python
from aegis.errors import AegisAuthError, AegisBalanceError, AegisNodeError

try:
    res = aegis.get("https://example.com", country="JP")
except AegisBalanceError:
    pass  # top up at aegisprivacy.org/dashboard
except AegisNodeError:
    pass  # no nodes available in that country
except AegisAuthError:
    pass  # invalid API key
```

## Pricing

| | Cost |
|---|---|
| Per request | $0.001 USDC |
| Residential exit | +$0.0005 USDC |
| Bandwidth | $0.005 USDC / MB |

Get an API key at [aegisprivacy.org/agent](https://aegisprivacy.org/agent).
