burnwatch 0.1.0__tar.gz

burnwatch-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: burnwatch
+Version: 0.1.0
+Summary: Burnwatch SDK — mirror your AI agent's payments to Burnwatch for spend monitoring.
+Project-URL: Homepage, https://getburnwatch.southforgeai.com
+Project-URL: Repository, https://github.com/tsouth89/burnwatch-app
+Project-URL: Documentation, https://github.com/tsouth89/burnwatch-app/blob/main/sdk/README.md
+Requires-Python: >=3.9

burnwatch-0.1.0/README.md

@@ -0,0 +1,107 @@
+# Burnwatch SDK (Python)
+
+A thin, **stdlib-only** shim that mirrors your AI agent's payments to Burnwatch for spend
+monitoring. Observe-only: it sends payment *metadata* (amount, recipient, resource, rail), never
+your keys or funds, and it's **fail-open** — if Burnwatch is unreachable, your agent keeps paying.
+
+## Install
+
+```bash
+pip install burnwatch
+```
+
+Or directly from GitHub (before PyPI release):
+
+```bash
+pip install "burnwatch @ git+https://github.com/tsouth89/burnwatch-app.git#subdirectory=sdk"
+```
+
+## Endpoint
+
+Use your Burnwatch deployment base URL (no `/ingest` suffix — the client adds `/ingest/payments`):
+
+- Production: `https://burnwatch.southforgeai.com`
+- Local dev: `http://localhost:8010`
+
+Create an ingest token in the dashboard (**Settings → Collector setup**) or via
+`python -m scripts.make_token` on the backend.
+
+## Basic use
+
+```python
+from burnwatch import BurnwatchClient
+
+with BurnwatchClient(endpoint="https://burnwatch.southforgeai.com", token="bw_your_token") as bw:
+    bw.record(
+        agent_ref="agent_7f3c",          # stable agent id
+        agent_name="research-bot",       # optional; used when auto-provisioning
+        amount=0.002,
+        recipient="api.weather.dev",     # payee / endpoint / address
+        resource="GET /forecast",
+        rail="x402",
+        currency="USDC",
+        context={"tx_hash": "0xabc...", "chain_id": "eip155:8453"},  # optional, public only
+    )
+```
+
+Calls are **buffered and flushed in the background** (every `flush_interval` seconds, or when
+`max_batch` is reached), so `record()` never blocks your agent. Set `enabled=False` to disable
+mirroring in tests without changing call sites.
+
+## Context metadata
+
+Pass optional `context` for dedup and richer detection. **Never** include private keys, mnemonics,
+seeds, or raw signatures — the API returns **422** if forbidden keys are present.
+
+| Key | Purpose |
+|-----|---------|
+| `tx_hash`, `payment_id`, `transaction_id` | Dedup (preferred over content hash) |
+| `asset` | Token symbol when different from `currency` |
+| `chain_id` | e.g. `eip155:8453` |
+| `facilitator` | `coinbase`, self-hosted, etc. |
+| `wallet_provider` | `cdp`, `wdk`, `agentkit`, etc. |
+| `network` | `mainnet` or `testnet` |
+
+## x402 wrapper
+
+Use `X402Monitor` (or `PaymentMirror` metadata) to wrap your existing x402 HTTP client:
+
+```python
+from burnwatch import BurnwatchClient, X402Monitor
+
+with BurnwatchClient(endpoint="https://burnwatch.southforgeai.com", token="bw_...") as bw:
+    mon = X402Monitor(bw, agent_ref="agent_7f3c", agent_name="research-bot")
+    resp = mon.paid_get(x402_client.get, "https://api.weather.dev/forecast", max_amount=0.01)
+```
+
+Or mirror manually after your own client returns:
+
+```python
+resp = x402_client.get(url, max_amount=price)
+mon.after_payment(resp, recipient=url, resource="GET /forecast")
+```
+
+See `examples/x402_wrapper.py` for a runnable demo with a fake x402 client.
+
+## Manual seam
+
+If you prefer an explicit `record()` at the call site:
+
+```python
+def paid_get(url, price, *, bw, agent_ref):
+    resp = x402_client.get(url, max_amount=price)   # your real x402 call
+    bw.record(agent_ref=agent_ref, amount=resp.amount_paid, recipient=url, resource="GET")
+    return resp
+```
+
+## Examples
+
+```bash
+BURNWATCH_ENDPOINT=http://localhost:8010 BURNWATCH_TOKEN=bw_... python examples/quickstart.py
+```
+
+## What Burnwatch detects
+
+The backend runs 10 transparent rules after warm-up (velocity, unknown payees, drain bursts,
+off-pattern destinations, amount spikes, off-hours spend, new rails, concentration, counterparty
+velocity, asset anomalies). See the root [`README.md`](../README.md) for the full table.

burnwatch-0.1.0/burnwatch/__init__.py

@@ -0,0 +1,19 @@
+"""Burnwatch SDK — observe-only spend mirroring for AI agents.
+
+Wrap your agent's payment client, call ``record()`` after each payment, and Burnwatch watches the
+metadata for drains, overspends, and unknown counterparties. It never holds your keys or funds and
+never sits in the payment path: mirroring is async, batched, and fail-open — if Burnwatch is
+unreachable, your agent keeps paying as normal.
+
+    from burnwatch import BurnwatchClient
+
+    bw = BurnwatchClient(endpoint="https://burnwatch.southforgeai.com", token="bw_...")
+    # ... after your agent makes an x402 payment ...
+    bw.record(agent_ref="agent_7f3c", amount=0.002, recipient="api.weather.dev", resource="GET /forecast")
+    bw.close()  # or use `with BurnwatchClient(...) as bw:`
+"""
+from burnwatch.client import BurnwatchClient
+from burnwatch.x402 import PaymentMirror, X402Monitor
+
+__all__ = ["BurnwatchClient", "X402Monitor", "PaymentMirror"]
+__version__ = "0.1.0"

burnwatch-0.1.0/burnwatch/client.py

@@ -0,0 +1,130 @@
+"""The Burnwatch client: buffer payment metadata and mirror it outbound, async and fail-open."""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any
+
+log = logging.getLogger("burnwatch")
+
+__sdk_version__ = "0.1.0"
+
+
+class BurnwatchClient:
+    """Mirrors agent payments to the Burnwatch backend.
+
+    Design rules (CLAUDE.md §3): outbound-only, metadata-only, never in the money path. Every
+    network operation swallows its errors — a monitoring failure must never break the agent.
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        token: str,
+        *,
+        flush_interval: float = 2.0,
+        max_batch: int = 100,
+        timeout: float = 3.0,
+        enabled: bool = True,
+    ) -> None:
+        self._url = endpoint.rstrip("/") + "/ingest/payments"
+        self._token = token
+        self._flush_interval = flush_interval
+        self._max_batch = max_batch
+        self._timeout = timeout
+        self._enabled = enabled
+
+        self._buf: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        if enabled:
+            self._thread = threading.Thread(target=self._loop, name="burnwatch-flush", daemon=True)
+            self._thread.start()
+
+    # -- public API -----------------------------------------------------------
+
+    def record(
+        self,
+        *,
+        agent_ref: str,
+        amount: float,
+        recipient: str,
+        resource: str | None = None,
+        currency: str = "USDC",
+        rail: str = "x402",
+        status: str = "paid",
+        ts: datetime | None = None,
+        agent_name: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        """Queue one payment for mirroring. Non-blocking; never raises."""
+        if not self._enabled:
+            return
+        event = {
+            "agent_ref": agent_ref,
+            "amount": amount,
+            "recipient": recipient,
+            "resource": resource,
+            "currency": currency,
+            "rail": rail,
+            "status": status,
+            "ts": (ts or datetime.now(timezone.utc)).isoformat(),
+        }
+        if agent_name:
+            event["agent_name"] = agent_name
+        if context:
+            event["context"] = context
+        with self._lock:
+            self._buf.append(event)
+            full = len(self._buf) >= self._max_batch
+        if full:
+            self.flush()
+
+    def flush(self) -> None:
+        """Send any buffered events now. Fail-open: network/HTTP errors are logged, not raised."""
+        with self._lock:
+            if not self._buf:
+                return
+            batch, self._buf = self._buf, []
+        try:
+            self._post({"events": batch, "sdk_version": __sdk_version__})
+        except Exception as exc:  # noqa: BLE001 — monitoring must never break the caller
+            log.debug("burnwatch flush failed (%s events dropped): %s", len(batch), exc)
+
+    def close(self) -> None:
+        """Stop the background flusher and send anything still buffered."""
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=self._timeout + 1)
+        self.flush()
+
+    def __enter__(self) -> "BurnwatchClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -- internals ------------------------------------------------------------
+
+    def _loop(self) -> None:
+        while not self._stop.wait(self._flush_interval):
+            self.flush()
+
+    def _post(self, payload: dict[str, Any]) -> None:
+        req = urllib.request.Request(
+            self._url,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Authorization": f"Bearer {self._token}", "Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+            if resp.status >= 400:
+                log.debug("burnwatch ingest returned %s", resp.status)
+
+
+# silence "no handler" warnings while staying quiet by default
+log.addHandler(logging.NullHandler())

burnwatch-0.1.0/burnwatch/x402.py

@@ -0,0 +1,163 @@
+"""x402 payment wrapper — one-line integration over any paid HTTP client.
+
+Burnwatch does not ship an x402 transport; this module wraps *your* client and mirrors metadata
+after each successful payment. Fail-open: recording errors never propagate to the caller.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from burnwatch.client import BurnwatchClient
+
+
+def _extract_amount(result: Any, attr: str, fallback: float | None) -> float:
+    if isinstance(result, dict):
+        val = result.get(attr, result.get("amount"))
+    else:
+        val = getattr(result, attr, None)
+        if val is None:
+            val = getattr(result, "amount", None)
+    if val is None:
+        if fallback is None:
+            return 0.0
+        return float(fallback)
+    return float(val)
+
+
+@dataclass(frozen=True)
+class PaymentMirror:
+    """Normalized payment metadata passed to Burnwatch after an x402 call."""
+
+    amount: float
+    recipient: str
+    resource: str | None = None
+    currency: str = "USDC"
+    rail: str = "x402"
+    status: str = "paid"
+    context: dict[str, Any] | None = None
+
+
+class X402Monitor:
+    """Wrap paid x402 calls and auto-mirror metadata to Burnwatch.
+
+    Example::
+
+        bw = BurnwatchClient(endpoint="https://burnwatch.example.com", token="bw_...")
+        mon = X402Monitor(bw, agent_ref="agent_7f3c", agent_name="research-bot")
+
+        # pass your real x402 client's get function
+        resp = mon.paid_get(x402_client.get, "https://api.weather.dev/forecast", max_amount=0.01)
+    """
+
+    def __init__(
+        self,
+        client: BurnwatchClient,
+        *,
+        agent_ref: str,
+        agent_name: str | None = None,
+    ) -> None:
+        self._client = client
+        self._agent_ref = agent_ref
+        self._agent_name = agent_name
+
+    def mirror(self, payment: PaymentMirror) -> None:
+        """Record a completed payment explicitly."""
+        self._client.record(
+            agent_ref=self._agent_ref,
+            agent_name=self._agent_name,
+            amount=payment.amount,
+            recipient=payment.recipient,
+            resource=payment.resource,
+            currency=payment.currency,
+            rail=payment.rail,
+            status=payment.status,
+            context=payment.context,
+        )
+
+    def after_payment(
+        self,
+        result: Any,
+        *,
+        recipient: str,
+        resource: str | None = None,
+        amount_attr: str = "amount_paid",
+        amount_fallback: float | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> Any:
+        """Mirror an already-completed payment; returns ``result`` unchanged."""
+        self.mirror(
+            PaymentMirror(
+                amount=_extract_amount(result, amount_attr, amount_fallback),
+                recipient=recipient,
+                resource=resource,
+                context=context,
+            )
+        )
+        return result
+
+    def paid_call(
+        self,
+        pay_fn: Callable[..., Any],
+        recipient: str,
+        *,
+        resource: str | None = None,
+        amount_attr: str = "amount_paid",
+        amount_fallback: float | None = None,
+        context: dict[str, Any] | None = None,
+        **pay_kwargs: Any,
+    ) -> Any:
+        """Call ``pay_fn(**pay_kwargs)``, mirror metadata, return the result."""
+        result = pay_fn(**pay_kwargs)
+        return self.after_payment(
+            result,
+            recipient=recipient,
+            resource=resource,
+            amount_attr=amount_attr,
+            amount_fallback=amount_fallback,
+            context=context,
+        )
+
+    def paid_get(
+        self,
+        get_fn: Callable[..., Any],
+        url: str,
+        *,
+        max_amount: float | None = None,
+        resource: str | None = None,
+        amount_attr: str = "amount_paid",
+        **get_kwargs: Any,
+    ) -> Any:
+        """Common x402 GET pattern: ``get_fn(url, max_amount=...)`` then mirror."""
+        kwargs = dict(get_kwargs)
+        if max_amount is not None and "max_amount" not in kwargs:
+            kwargs["max_amount"] = max_amount
+        return self.paid_call(
+            lambda: get_fn(url, **kwargs),
+            url,
+            resource=resource or f"GET {url}",
+            amount_attr=amount_attr,
+            amount_fallback=max_amount,
+        )
+
+    def paid_post(
+        self,
+        post_fn: Callable[..., Any],
+        url: str,
+        *,
+        max_amount: float | None = None,
+        resource: str | None = None,
+        amount_attr: str = "amount_paid",
+        **post_kwargs: Any,
+    ) -> Any:
+        """Common x402 POST pattern: ``post_fn(url, max_amount=...)`` then mirror."""
+        kwargs = dict(post_kwargs)
+        if max_amount is not None and "max_amount" not in kwargs:
+            kwargs["max_amount"] = max_amount
+        return self.paid_call(
+            lambda: post_fn(url, **kwargs),
+            url,
+            resource=resource or f"POST {url}",
+            amount_attr=amount_attr,
+            amount_fallback=max_amount,
+        )

burnwatch-0.1.0/burnwatch.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: burnwatch
+Version: 0.1.0
+Summary: Burnwatch SDK — mirror your AI agent's payments to Burnwatch for spend monitoring.
+Project-URL: Homepage, https://getburnwatch.southforgeai.com
+Project-URL: Repository, https://github.com/tsouth89/burnwatch-app
+Project-URL: Documentation, https://github.com/tsouth89/burnwatch-app/blob/main/sdk/README.md
+Requires-Python: >=3.9

burnwatch-0.1.0/burnwatch.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+burnwatch/__init__.py
+burnwatch/client.py
+burnwatch/x402.py
+burnwatch.egg-info/PKG-INFO
+burnwatch.egg-info/SOURCES.txt
+burnwatch.egg-info/dependency_links.txt
+burnwatch.egg-info/top_level.txt

burnwatch-0.1.0/burnwatch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

burnwatch-0.1.0/burnwatch.egg-info/top_level.txt

@@ -0,0 +1 @@
+burnwatch

burnwatch-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "burnwatch"
+version = "0.1.0"
+description = "Burnwatch SDK — mirror your AI agent's payments to Burnwatch for spend monitoring."
+requires-python = ">=3.9"
+dependencies = []  # stdlib-only on purpose: a monitor must never add weight or break your agent
+
+[build-system]
+requires = ["setuptools>=70"]
+build-backend = "setuptools.build_meta"
+
+[project.urls]
+Homepage = "https://getburnwatch.southforgeai.com"
+Repository = "https://github.com/tsouth89/burnwatch-app"
+Documentation = "https://github.com/tsouth89/burnwatch-app/blob/main/sdk/README.md"
+
+[tool.setuptools.packages.find]
+include = ["burnwatch*"]

burnwatch-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+