Metadata-Version: 2.5
Name: payagentic
Version: 0.1.1
Summary: Pay-per-use API access for AI agents: x402 payments, wallets and spend policies.
Project-URL: Homepage, https://payagentic.ai/platform/developers
Project-URL: Documentation, https://payagentic.ai/sdks#py
Project-URL: Examples, https://payagentic.ai/docs/examples
Project-URL: Pricing, https://payagentic.ai/pricing
Project-URL: Support, https://payagentic.ai/contact
License-Expression: MIT
License-File: LICENSE
Keywords: agent-payments,ai-agents,paid-api,payagentic,usdc,x402
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: attrs>=24.0
Requires-Dist: cryptography>=48.0.0
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2.10
Requires-Dist: python-dateutil>=2.9
Requires-Dist: rfc8785==0.1.4
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'
Requires-Dist: types-python-dateutil>=2.9; extra == 'dev'
Description-Content-Type: text/markdown

# payagentic

Build AI agents that buy paid API data with programmable stablecoin wallets and spend-policy controls on supported USDC and USDT rails. PayAgentic SDKs connect your server to the gateway; the platform's subscriptions and transaction charges are separate from the SDK's MIT license.

[Developer home](https://payagentic.ai/platform/developers) · [Runnable buyer + merchant example](https://payagentic.ai/docs/examples) · [SDK reference](https://payagentic.ai/sdks) · [Pricing](https://payagentic.ai/pricing) · [Integration support](mailto:developers@payagentic.ai)

## Start with a working example

Download the [local API commerce demo](https://payagentic.ai/examples/api-commerce.zip). It includes both sides, installation instructions, expected output and automated tests. Node.js 22+ runs the demo, including for Python and Go developers who want to inspect the HTTP payment exchange. It uses simulated authorization, moves no funds, and does not validate settlement.

For your own integration, use the [quickstart](https://payagentic.ai/docs/quickstart), finish asynchronous wallet provisioning, and configure a test API key, gateway URL and wallet ID. The key belongs in your server environment, never browser code. Registered merchant origin and endpoint setup is required to exercise the platform transaction fee flow.

These are pre-1.0 SDKs. A source checkout may be newer than the published package; pin and test a release before upgrading. See the registry's release history for available versions.

## Install

Version 0.1.1 includes the runtime dependencies missing from 0.1.0. Pin the version below for a reproducible installation. If it is not yet available in the registry, use the source-built package in the [downloadable example](https://payagentic.ai/docs/examples).

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

Requires Python 3.13+.

## Usage

### Sync

```python
import os
from payagentic import PayAgentic

client = PayAgentic(
    api_key=os.environ["PAYAGENTIC_API_KEY"],
    base_url=os.environ["PAYAGENTIC_BASE_URL"],
    x402_wallet_id=os.environ["PAYAGENTIC_WALLET_ID"],
)
# Or from env: PAYAGENTIC_API_KEY, PAYAGENTIC_AGENT_ID, PAYAGENTIC_BASE_URL

wallets = client.wallets.list_wallets()

# x402 paywall walker
response = client.x402.fetch(os.environ["PAYAGENTIC_RESOURCE_URL"])
```

### Async

```python
import os
from payagentic import AsyncPayAgentic

# Inside your async function:
async with AsyncPayAgentic(
    api_key=os.environ["PAYAGENTIC_API_KEY"],
    base_url=os.environ["PAYAGENTIC_BASE_URL"],
    x402_wallet_id=os.environ["PAYAGENTIC_WALLET_ID"],
) as client:
    wallets = await client.wallets.list_wallets()
    response = await client.x402.fetch(os.environ["PAYAGENTIC_RESOURCE_URL"])
```

### 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.1   # bumps version, builds, uv publish, tags
```

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

## License

MIT
