Metadata-Version: 2.4
Name: deltablab-paygate
Version: 0.1.1
Summary: Python SDK for PayGate x402 payment flows
Author: DeltaBlab
License: MIT
Project-URL: Homepage, https://github.com/tomo-inc/paygate
Project-URL: Repository, https://github.com/tomo-inc/paygate
Keywords: paygate,x402,base,usdc,payments
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: cloud
Requires-Dist: httpx<1.0,>=0.28; extra == "cloud"
Provides-Extra: client
Requires-Dist: httpx<1.0,>=0.28; extra == "client"
Requires-Dist: eth-account<1.0,>=0.13; extra == "client"
Provides-Extra: publisher
Requires-Dist: httpx<1.0,>=0.28; extra == "publisher"
Requires-Dist: fastapi<1.0,>=0.115; extra == "publisher"
Requires-Dist: starlette<1.0,>=0.46; extra == "publisher"
Requires-Dist: uvicorn<1.0,>=0.34; extra == "publisher"

# deltablab-paygate

Python SDK for PayGate Cloud management, Gateway Facade request orchestration, and x402-compatible payment retries.

## Install

Paid client:

```bash
pip install "deltablab-paygate[client]"
```

Cloud management / webhook helpers:

```bash
pip install "deltablab-paygate[cloud]"
```

Publisher integrations:

```bash
pip install "deltablab-paygate[publisher]"
```

## Gateway publisher

Current public publisher path is the Cloud Gateway Facade. Use the gateway helpers for protected merchant routes.

```python
import os

import uvicorn
from fastapi import FastAPI

from paygate.publisher import create_fastapi_gateway

app = FastAPI()
paygate = create_fastapi_gateway(
    api_key=os.environ["PAYGATE_API_KEY"],
    publisher_id=os.environ["PAYGATE_PUBLISHER_ID"],
    env="dev",
)

@app.get("/v1/weather")
@paygate.protect(endpoint_id=os.environ["PAYGATE_WEATHER_ENDPOINT_ID"])
async def weather():
    return {"city": "Shanghai", "temp": 22}


if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)
```

For dynamic prepaid-balance flows, use `create_fastapi_metered(...)` and return
`{"quantity": "...", "body": ...}` from the protected handler.

## Gateway client

Current public client path is the gateway-aware paid client. It handles:

- `401 payer_auth_required`
- `402 payment_required`
- `payer_session` persistence
- `202 settling` polling

```python
import json
import os

from eth_account import Account

from paygate.client import create_gateway_client
from paygate.cloud import paygate_chain_id_for_environment

env = os.getenv("PAYGATE_ENV", "dev")
client = create_gateway_client(
    account=Account.from_key(os.environ["CLIENT_WALLET_PRIVATE_KEY"]),
    base_url="http://127.0.0.1:8000",
    payer_auth_chain_id=paygate_chain_id_for_environment(env),
)

response = client.get(
    "/v1/weather",
)
print(response.status_code)
print(json.dumps(response.json(), indent=2))
```

## Cloud management helpers

`paygate.cloud.PublisherCloudClient` and `AsyncPublisherCloudClient` now cover:

- `GET /supported`
- `POST /verify`
- `POST /settle`
- `/v1/gateway/*`
- `/v1/access-grants*`
- `/v1/usage-events`
- publishers/endpoints/webhooks/transactions/metrics

## Compatibility surfaces

Legacy helpers remain available for compatibility and migration:

- publisher compat: `from paygate.publisher.compat import create_fastapi_paygate, create_starlette_paygate`
- client compat: `from paygate.client.compat import create_relay_client, create_async_relay_client`
- client compat: `from paygate.client.compat import create_eip3009_client, create_async_eip3009_client`

PayGate Cloud URLs and chain IDs are built into the SDK. Examples typically use `env="dev"` for Base Sepolia development and `env="prod"` for Base mainnet production.

## Examples

Runnable examples live in [examples/README.md](./examples/README.md):

- `examples/publisher/register.py`
- `examples/publisher/fastapi_app.py`
- `examples/publisher/starlette_app.py`
- `examples/client/weather.py`
- `examples/client/llm_chat.py`
- `examples/client/company_search.py`
- `examples/client/premium_feed.py`
- `examples/cloud_ops/endpoints.py`
- `examples/cloud_ops/transactions.py`
- `examples/cloud_ops/metrics.py`
- `examples/cloud_ops/settlement_events.py`
- `examples/cloud_ops/webhook_register.py`
- `examples/cloud_ops/webhook_receiver.py`
