oceanalt-agentkit-hook 0.1.0__py3-none-any.whl

oceanalt_agentkit_hook/__init__.py

@@ -0,0 +1,184 @@
+"""oceanalt_agentkit_hook 0.1.0. Sync before-payment hook for Coinbase AgentKit (Python).
+
+Works with:
+  * coinbase/agentkit#1577: X402Config(before_payment=...) -> x402ClientSync.on_before_payment_creation.
+    Context is x402's PaymentCreationContext; we return AbortResult to block, None to allow.
+  * a dict context shaped like #1454 / #1613 (url, payTo, network, asset, amount, ...);
+    we return {"abort": True, "reason": ..., "code": ...} to block, None to allow.
+Never return a dict or a coroutine to the x402 SDK: it only blocks on isinstance(result, AbortResult).
+Not affiliated with Coinbase.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any, Literal
+from urllib.parse import urlsplit
+
+import httpx  # inside the agentkit repo itself, use `requests` instead (it is already a dependency)
+
+try:  # x402 SDK is optional; only needed for the #1577 context
+    from x402.schemas.hooks import AbortResult  # type: ignore
+except Exception:  # pragma: no cover
+    AbortResult = None  # type: ignore
+
+Policy = Literal["block", "allow"]
+_EVM = re.compile(r"^0x[0-9a-fA-F]{40}$")
+_V1 = {
+    "base": "eip155:8453", "base-sepolia": "eip155:84532", "ethereum": "eip155:1",
+    "polygon": "eip155:137", "arbitrum": "eip155:42161", "optimism": "eip155:10",
+    "avalanche": "eip155:43114", "solana": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+}
+
+
+def _normalize(ctx: Any) -> tuple[dict[str, Any], bool]:
+    """Return (normalized fields, is_sdk_context)."""
+    sel = getattr(ctx, "selected_requirements", None)
+    if sel is not None:
+        pr = getattr(ctx, "payment_required", None)
+        resource = getattr(pr, "resource", None)
+        url = getattr(resource, "url", None) or getattr(sel, "resource", None)  # v1 requirements carry resource
+        return {
+            "url": url,
+            "payTo": getattr(sel, "pay_to", None),
+            "network": getattr(sel, "network", None),
+            "asset": getattr(sel, "asset", None),
+            "amount": getattr(sel, "amount", None) or getattr(sel, "max_amount_required", None),
+        }, True
+    c = ctx if isinstance(ctx, dict) else {}
+    return {k: c.get(k) for k in ("url", "payTo", "network", "asset", "amount")}, False
+
+
+def _caip2(n: str | None) -> str | None:
+    if not n:
+        return None
+    return n if ":" in n else _V1.get(n.lower(), n)
+
+
+def _strip(u: str | None) -> str | None:
+    if not u:
+        return None
+    p = urlsplit(u)
+    if p.scheme not in ("http", "https") or not p.netloc:
+        return None
+    return f"{p.scheme}://{p.netloc}{p.path}"[:2048]
+
+
+def _decide_body(n: dict[str, Any], send_ref: bool) -> dict[str, Any]:
+    net, pay_to, asset, amount = _caip2(n["network"]), n["payTo"], n["asset"], n["amount"]
+    ref = _strip(n["url"]) if send_ref else None
+    if (net and net.startswith("eip155:") and pay_to and _EVM.match(pay_to)
+            and asset and _EVM.match(asset) and isinstance(amount, str) and amount.isdigit()):
+        intent = {"v": "1", "payee": pay_to, "amount_atomic": amount,
+                  "asset_id": f"{net}/erc20:{asset}", "network": net}
+        if ref:
+            intent["resource_ref"] = ref
+        return {"payment_intent": intent}
+    body: dict[str, Any] = {"to": pay_to}
+    if net:
+        body["network"] = net
+    if isinstance(amount, str) and re.fullmatch(r"\$\d+(\.\d+)?", amount):
+        body["amountUsdc"] = float(amount[1:])
+    return body
+
+
+def oceanalt_before_payment(
+    *,
+    endpoint: Literal["decide", "x402-decision", "x402-payee"] = "decide",
+    base_url: str = "https://oceanalt.com",
+    api_key: str | None = None,
+    paid_client: httpx.Client | None = None,  # an httpx client wrapped with x402 payment, for x402-* endpoints
+    on_review: Policy = "block",
+    on_error: Policy = "block",
+    on_missing_pay_to: Policy = "block",
+    timeout_s: float = 3.0,
+    code_prefix: str = "oceanalt:",
+    send_resource_ref: bool = True,
+    on_decision: Callable[[dict[str, Any]], None] | None = None,
+) -> Callable[[Any], Any]:
+    paid = endpoint != "decide"
+    if paid and paid_client is None:
+        raise ValueError(f"oceanalt_before_payment: endpoint {endpoint} needs paid_client")
+    client = paid_client or httpx.Client(timeout=timeout_s)
+    path = {"decide": "/api/decide", "x402-decision": "/api/x402/decision", "x402-payee": "/api/x402/payee"}[endpoint]
+    headers = {"content-type": "application/json", "user-agent": "oceanalt-agentkit-hook-py/0.1.0"}
+    if api_key:
+        headers["authorization"] = f"Bearer {api_key}"
+
+    def hook(ctx: Any) -> Any:
+        n, sdk = _normalize(ctx)
+
+        def emit(outcome: str, decision: str, code: str, response: Any = None) -> None:
+            if on_decision:
+                try:
+                    on_decision({"outcome": outcome, "decision": decision, "code": code,
+                                 "payTo": n["payTo"], "network": n["network"],
+                                 "url": _strip(n["url"]), "response": response})
+                except Exception:
+                    pass  # logging must never change the decision
+
+        def stop(decision: str, code: str, reason: str, response: Any = None) -> Any:
+            full, text = code_prefix + code, f"[OceanAlt] {reason}"[:300]
+            emit("aborted", decision, full, response)
+            if sdk:
+                if AbortResult is None:
+                    raise RuntimeError(text)  # SDK context without AbortResult import: raising still blocks
+                return AbortResult(reason=full, message=text)
+            return {"abort": True, "reason": text, "code": full}
+
+        def allow(decision: str, code: str, response: Any = None) -> None:
+            emit("allowed", decision, code_prefix + code, response)
+            return None
+
+        def unavailable(code: str, detail: str) -> Any:
+            if on_error == "allow":
+                return allow("unavailable", code)
+            return stop("unavailable", code, f"decision unavailable ({detail}); payment not signed")
+
+        if not n["payTo"]:
+            if on_missing_pay_to == "allow":
+                return allow("missing_pay_to", "payee.missing")
+            return stop("missing_pay_to", "payee.missing", "the selected payment option declares no payTo")
+
+        if endpoint == "x402-payee":
+            body: dict[str, Any] = {"pay_to": n["payTo"]}
+            if _caip2(n["network"]):
+                body["network"] = _caip2(n["network"])
+            if send_resource_ref and _strip(n["url"]):
+                body["resource_url"] = _strip(n["url"])
+        else:
+            body = _decide_body(n, send_resource_ref)
+
+        try:
+            r = client.post(base_url.rstrip("/") + path, json=body, headers=headers, timeout=timeout_s)
+        except httpx.TimeoutException:
+            return unavailable("unavailable.timeout", f"no answer within {timeout_s}s")
+        except httpx.HTTPError:
+            return unavailable("unavailable.network", "network error")
+        if r.status_code >= 400:
+            if r.status_code == 402 and not paid:
+                return unavailable("unavailable.quota", "free allowance used up; set api_key")
+            return unavailable(f"unavailable.http_{r.status_code}", f"HTTP {r.status_code}")
+        try:
+            j = r.json()
+        except ValueError:
+            return unavailable("unavailable.bad_json", "unreadable response")
+
+        raw = j.get("decision") if isinstance(j, dict) else None
+        d = raw if raw in ("allow", "decline") else "review"
+        if endpoint == "x402-payee":
+            reasons = j.get("reasons") or []
+            rc = reasons[0].get("code") if reasons and isinstance(reasons[0], dict) else None
+        else:
+            rc = j.get("reason_code")
+        rc = rc or (d if raw == d else "unrecognized_decision")
+        summary = j.get("summary") if isinstance(j.get("summary"), str) else f"payee {n['payTo']} {d}"
+
+        if d == "allow":
+            return allow("allow", rc, j)
+        if d == "decline":
+            return stop("decline", rc, summary, j)
+        return allow("review", rc, j) if on_review == "allow" else stop("review", rc, summary, j)
+
+    return hook

oceanalt_agentkit_hook-0.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: oceanalt-agentkit-hook
+Version: 0.1.0
+Summary: Sync before-payment check for Coinbase AgentKit x402 payments (AgentKit #1577 / x402 SDK on_before_payment_creation, and #1454-shaped dicts). Fail-closed by default. Not affiliated with Coinbase.
+License: MIT
+Project-URL: Homepage, https://oceanalt.com/en/api-docs
+Keywords: agentkit,x402,before_payment,agent-payments,aml
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25
+
+# oceanalt-agentkit-hook (Python)
+
+A synchronous before-payment check for Coinbase AgentKit x402 payments. Before anything is signed, it asks OceanAlt for a decision on the payee: `allow`, `review` or `decline`.
+
+- With the x402 SDK hook (`on_before_payment_creation`, used by AgentKit #1577) it returns `AbortResult` to block and `None` to allow. The SDK only blocks on `AbortResult`; a returned dict or a coroutine would let the payment through, so this package never returns those to the SDK.
+- With a dict context shaped like AgentKit #1454 it returns `{"abort": True, "reason": ..., "code": ...}` to block and `None` to allow.
+
+Defaults are fail-closed: `review`, an unreachable service, a timeout (3 s) and a missing `payTo` all block. Change with `on_review`, `on_error`, `on_missing_pay_to`, `timeout_s`.
+
+```python
+from oceanalt_agentkit_hook import oceanalt_before_payment
+
+client.on_before_payment_creation(oceanalt_before_payment())
+```
+
+It calls the free `POST https://oceanalt.com/api/decide`, sending the payee, network, asset, amount and the paid URL without its query string, so the service can also check the payee against that origin's own quote. Without a key the free endpoint allows 2,000 calls a month per source, then answers 402, which blocks payments under the default `on_error="block"`. For production agents, get a free key at https://oceanalt.com/en/api-keys (email only, 5,000 calls a month) and pass it as `api_key`. OceanAlt holds no keys and moves no money. Not affiliated with Coinbase. MIT.

oceanalt_agentkit_hook-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+oceanalt_agentkit_hook/__init__.py,sha256=2Qr8yzMoRE6sPT8KDjcmbGnkz3EZdbWsW_AuyiEkVvE,8196
+oceanalt_agentkit_hook-0.1.0.dist-info/METADATA,sha256=gImu_YOGFHT7Y-G-cF0KhWPQd07G4SRqGW8QjG613Cg,2017
+oceanalt_agentkit_hook-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+oceanalt_agentkit_hook-0.1.0.dist-info/top_level.txt,sha256=TiWy8LvT6Rl3PlS1uB6ukmnUcx_51ZeJVu7_e_jUCLM,23
+oceanalt_agentkit_hook-0.1.0.dist-info/RECORD,,

oceanalt_agentkit_hook-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

oceanalt_agentkit_hook-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+oceanalt_agentkit_hook