Metadata-Version: 2.4
Name: ptm-x402-monitor
Version: 0.1.0
Summary: Open x402 resource-server extension that forwards settlement events to a post-transaction monitoring API (PTAPI)
Project-URL: Homepage, https://github.com/Git332/Post-Transaction-Monitoring
Project-URL: Repository, https://github.com/Git332/Post-Transaction-Monitoring
Author: Git332
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: x402>=2.16
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# ptm-x402-monitor

An open [x402](https://x402.org) resource-server extension that forwards
settlement events to a post-transaction monitoring API (PTAPI or any
compatible ingest endpoint). Install it alongside your own x402 facilitator
or resource server — no changes to your payment logic, no protocol fork.

This is deliberately the thin half: it only observes settlements and forwards
them, it never changes payment behavior. The monitoring/anomaly-detection/
reconciliation logic lives entirely on the receiving API, not here.

## Usage

```python
from x402 import x402ResourceServerSync
from ptm_x402_monitor import MonitorConfig, PostTransactionMonitorExtension

server = x402ResourceServerSync(facilitator_client)
# ... register your payment schemes, initialize() as usual ...

server.register_extension(
    PostTransactionMonitorExtension(
        MonitorConfig(
            ingest_url="https://<your-ptapi-instance>/events/ingest",
            api_key="ptmk_...",
        )
    )
)
```

Get an `api_key` via `POST /tenants/provision` on the target PTAPI instance
(self-serve, paid in stablecoin over x402 — no signup form) or from your
operator's own tenant bootstrap script.

Works with both `x402ResourceServer` (async) and `x402ResourceServerSync` —
the hooks are plain synchronous methods, which both server variants accept.

## Guarantees

- Never raises. A forwarding failure (network error, ingest API down, bad
  API key) is logged (`logging.getLogger("ptm_x402_monitor")`) and swallowed
  — it will never break the payment flow it's observing.
- Short HTTP timeout (`MonitorConfig.timeout_seconds`, default 3s) so a slow
  ingest endpoint can't meaningfully delay your settle() response.

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check .
mypy src/ptm_x402_monitor
```

## Releasing

Published to [PyPI](https://pypi.org/project/ptm-x402-monitor/) via GitHub
Actions Trusted Publishing (OIDC) — no token stored anywhere
(`.github/workflows/publish.yml`). One-time setup on PyPI: Account Settings →
Publishing → add a pending publisher with owner `Git332`, repo
`Post-Transaction-Monitoring`, workflow `publish.yml`, environment `pypi-ptm-x402-monitor`.

To cut a release: bump `version` in `pyproject.toml`, then push a tag matching
`ptm-x402-monitor-vX.Y.Z` (or create a GitHub Release from that tag) — this
triggers the publish job for this package only.
