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 · Runnable buyer + merchant example · SDK reference · Pricing · Integration support

Start with a working example

Download the local API commerce demo. 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, 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.

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

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

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:

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

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:

from payagentic.models import Wallet, PaymentResponse, MandateListItem

Generated transport

The HTTP transport in src/payagentic/_generated/ is generated by openapi-python-client from the gateway's OpenAPI spec at ../../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)

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

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