Metadata-Version: 2.4
Name: payagentic
Version: 0.1.0
Summary: PayAgentic Python SDK — Agent payments for AI agents
License-Expression: MIT
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.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: cryptography>=48.0.0
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2.10
Provides-Extra: dev
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# payagentic

Official Python SDK for [PayAgentic](https://payagentic.ai) — programmable USDC wallets for AI agents that pay external APIs over [x402](https://www.x402.org/).

## Install

```bash
pip install payagentic
# or
uv add payagentic
poetry add payagentic
```

Requires Python 3.13+.

## Usage

### Sync

```python
from payagentic import PayAgentic

client = PayAgentic(api_key="pa_test_…")
# Or from env: PAYAGENTIC_API_KEY, PAYAGENTIC_AGENT_ID, PAYAGENTIC_BASE_URL

wallets = client.wallets.list_wallets()
payment = client.payments.propose_payment(body={...})
status = client.payments.get_payment(id=payment.id)

# x402 paywall walker
response = client.x402.fetch("https://api.vendor.com/paid-endpoint")
```

### Async

```python
from payagentic import AsyncPayAgentic

async with AsyncPayAgentic(api_key="pa_test_…") as client:
    wallets = await client.wallets.list_wallets()
    response = await client.x402.fetch("https://api.vendor.com/paid-endpoint")
```

### Typed errors

Non-2xx responses raise typed exceptions you can catch by type:

```python
from payagentic import PayAgentic, UnauthorizedError, RateLimitError, ValidationError

try:
    client.wallets.list_wallets()
except UnauthorizedError:
    ...
except RateLimitError:
    ...
```

Full hierarchy: `PayAgenticError` → `{Conflict, Forbidden, Internal, Network, NotFound, RateLimit, ServiceUnavailable, Unauthorized, Validation}Error`. Use `payagentic.is_retryable(err)` for retry classification.

### Mandate signer

```python
from payagentic import LocalMandateSigner

signer = LocalMandateSigner.from_pem("path/to/key.pem")
mandate = signer.sign({...})
```

### Pydantic models

All request/response shapes are Pydantic v2 models, re-exported under `payagentic.models`:

```python
from payagentic.models import Wallet, PaymentResponse, MandateListItem
```

## Generated transport

The HTTP transport in `src/payagentic/_generated/` is generated by [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) from the gateway's OpenAPI spec at [`../../api/openapi.json`](../../api/openapi.json). Regenerate with the monorepo's `just gen-sdk-py`.

`src/payagentic/_generated/` is marked `linguist-generated=true`. Don't edit those files directly — modify the gateway's `#[utoipa::path]` annotations + regenerate.

## Development (from the monorepo)

```bash
just gen-sdk-py    # regenerate from api/openapi.json
cd sdks/python
uv run pytest
uv run mypy src/payagentic
uv run ruff check src tests
uv build
```

## Publishing

```bash
just release-py 0.1.0   # bumps version, builds, uv publish, tags
```

Needs PyPI API token in `~/.config/uv/credentials.toml` or `UV_PUBLISH_TOKEN` env.

## License

MIT
