voidly-pay 0.1.1__py3-none-any.whl

voidly_pay/__init__.py

@@ -0,0 +1,479 @@
+"""Voidly Pay — Python SDK for agent-to-agent payments.
+
+Quick start:
+
+    from voidly_pay import VoidlyPay
+    pay = VoidlyPay()                                 # mints + persists keypair on first use
+    pay.transfer(to="did:voidly:provider", amount=0.5) # 0.5 credits
+
+The SDK signs envelopes with Ed25519 and POSTs them to the configured API
+host (default: https://api.voidly.ai). Keys are persisted to
+~/.voidly-pay/keypair.json with mode 0600.
+
+For server-side x402 paywalls, see ``VoidlyPay.create_quote`` and
+``VoidlyPay.verify_payment``. For client-side fetch-with-pay, see
+``VoidlyPay.request_with_pay``.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Optional
+
+import nacl.signing
+import requests
+
+__version__ = "0.1.0"
+
+DEFAULT_API = "https://api.voidly.ai"
+MICRO_PER_CREDIT = 1_000_000
+DEFAULT_EXPIRY_MINUTES = 30
+
+
+# ─── Errors ────────────────────────────────────────────────────────────────
+
+
+class VoidlyPayError(Exception):
+    def __init__(self, code: str, message: str, status: int, hint: str | None = None, raw: Any = None):
+        super().__init__(f"[{code}] {message}")
+        self.code = code
+        self.status = status
+        self.hint = hint
+        self.raw = raw
+
+
+# ─── Canonical JSON ───────────────────────────────────────────────────────
+
+
+def canonicalize(value: Any) -> str:
+    """Same canonical JSON the Worker expects: sorted keys, no whitespace,
+    omit None-valued keys, strict number/string serialization."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        # Server only accepts integers in amount fields. We still preserve
+        # repr for any float-valued metadata.
+        return repr(value)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(canonicalize(v) for v in value) + "]"
+    if isinstance(value, Mapping):
+        keys = sorted(k for k, v in value.items() if v is not None)
+        return "{" + ",".join(json.dumps(k, ensure_ascii=False) + ":" + canonicalize(value[k]) for k in keys) + "}"
+    raise TypeError(f"unsupported type for canonicalization: {type(value)}")
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return canonicalize(value).encode("utf-8")
+
+
+# ─── DID derivation ───────────────────────────────────────────────────────
+
+_BASE58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+def _b58encode(data: bytes) -> str:
+    if not data:
+        return ""
+    n = int.from_bytes(data, "big")
+    out = ""
+    while n > 0:
+        n, rem = divmod(n, 58)
+        out = _BASE58[rem] + out
+    for b in data:
+        if b == 0:
+            out = _BASE58[0] + out
+        else:
+            break
+    return out
+
+
+def did_from_pubkey(pubkey: bytes) -> str:
+    return f"did:voidly:{_b58encode(pubkey[:16])}"
+
+
+# ─── Storage ──────────────────────────────────────────────────────────────
+
+
+@dataclass
+class Keypair:
+    did: str
+    secret_key: bytes
+    public_key: bytes
+
+
+def _default_storage_path() -> Path:
+    home = Path.home()
+    return home / ".voidly-pay" / "keypair.json"
+
+
+def _load_or_create_keypair(path: Path | None, did_override: str | None = None) -> Keypair:
+    if path is None:
+        path = _default_storage_path()
+    if path.exists():
+        try:
+            j = json.loads(path.read_text())
+            sk = base64.b64decode(j["secret_key"])
+            sk_obj = nacl.signing.SigningKey(sk[:32])  # nacl expects 32-byte seed
+            pk = bytes(sk_obj.verify_key)
+            did = did_override or j.get("did") or did_from_pubkey(pk)
+            return Keypair(did=did, secret_key=bytes(sk_obj._signing_key), public_key=pk)
+        except Exception:
+            # corrupt file — back it up and mint fresh
+            path.rename(path.with_suffix(".corrupt"))
+    sk_obj = nacl.signing.SigningKey.generate()
+    pk = bytes(sk_obj.verify_key)
+    did = did_override or did_from_pubkey(pk)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # nacl.signing internal "_signing_key" is the 64-byte tweetnacl-compatible key
+    sk_full = bytes(sk_obj._signing_key)
+    path.write_text(json.dumps({"did": did, "secret_key": base64.b64encode(sk_full).decode()}))
+    os.chmod(path, 0o600)
+    return Keypair(did=did, secret_key=sk_full, public_key=pk)
+
+
+# ─── Main client ──────────────────────────────────────────────────────────
+
+
+class VoidlyPay:
+    def __init__(
+        self,
+        api_url: str | None = None,
+        did: str | None = None,
+        secret_key: bytes | None = None,
+        storage_path: Path | str | None = None,
+        default_expiry_minutes: int = DEFAULT_EXPIRY_MINUTES,
+        session: requests.Session | None = None,
+    ):
+        self.api_url = (api_url or DEFAULT_API).rstrip("/")
+        self.default_expiry_ms = default_expiry_minutes * 60_000
+        self.session = session or requests.Session()
+        if secret_key is not None:
+            sk_obj = nacl.signing.SigningKey(secret_key[:32])
+            pk = bytes(sk_obj.verify_key)
+            self._kp = Keypair(did=did or did_from_pubkey(pk), secret_key=bytes(sk_obj._signing_key), public_key=pk)
+        else:
+            sp = Path(storage_path) if storage_path else None
+            self._kp = _load_or_create_keypair(sp, did)
+        self.did = self._kp.did
+
+    # ─── Crypto ────────────────────────────────────────────────────────────
+
+    @property
+    def public_key(self) -> str:
+        """Public key as base64 (32 bytes). Used to register with the relay."""
+        return base64.b64encode(self._kp.public_key).decode()
+
+    def _sign(self, env: dict) -> str:
+        msg = canonical_bytes(env)
+        sig = nacl.signing.SigningKey(self._kp.secret_key[:32]).sign(msg).signature
+        return base64.b64encode(sig).decode()
+
+    def _now_iso(self) -> str:
+        from datetime import datetime, timezone
+        return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+    def _expires(self, ms: int | None = None) -> str:
+        from datetime import datetime, timezone, timedelta
+        return (datetime.now(timezone.utc) + timedelta(milliseconds=ms or self.default_expiry_ms)).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+    # ─── HTTP ──────────────────────────────────────────────────────────────
+
+    def _req(self, method: str, path: str, body: Any = None, idempotency: str | None = None) -> dict:
+        headers = {"accept": "application/json"}
+        if body is not None:
+            headers["content-type"] = "application/json"
+        if idempotency:
+            headers["idempotency-key"] = idempotency
+        url = f"{self.api_url}{path}"
+        r = self.session.request(method, url, json=body, headers=headers, timeout=30)
+        try:
+            data = r.json() if r.text else {}
+        except json.JSONDecodeError:
+            data = {"raw": r.text}
+        if not r.ok:
+            err = data.get("error", {}) if isinstance(data, dict) else {}
+            raise VoidlyPayError(
+                code=err.get("code") or data.get("reason") or f"http_{r.status_code}",
+                message=err.get("message") or data.get("reason") or f"request failed: {r.status_code}",
+                status=r.status_code,
+                hint=err.get("hint"),
+                raw=data,
+            )
+        return data
+
+    # ─── Wallet ────────────────────────────────────────────────────────────
+
+    def ensure_wallet(self, did: str | None = None) -> dict:
+        return self._req("POST", "/v1/pay/wallet", {"did": did or self.did}).get("wallet", {})
+
+    def balance(self, did: str | None = None) -> dict:
+        target = did or self.did
+        r = self._req("GET", f"/v1/pay/wallet/{target}")
+        w = r.get("wallet", {})
+        return {
+            "balance_micro": w.get("balance_credits", 0),
+            "balance_credits": w.get("balance_credits", 0) / MICRO_PER_CREDIT,
+            "locked_micro": w.get("locked_credits", 0),
+            "daily_cap_micro": w.get("daily_cap_credits", 0),
+            "per_tx_cap_micro": w.get("per_tx_cap_credits", 0),
+            "frozen": bool(w.get("frozen")),
+        }
+
+    # ─── Transfer ──────────────────────────────────────────────────────────
+
+    def transfer(self, to: str, amount: float, memo: str | None = None, expires_in_minutes: int | None = None) -> dict:
+        try:
+            self.ensure_wallet()
+        except VoidlyPayError:
+            pass
+        env = {
+            "schema": "voidly-credit-transfer/v1",
+            "from_did": self.did,
+            "to_did": to,
+            "amount_micro": round(amount * MICRO_PER_CREDIT),
+            "memo": memo,
+            "nonce": uuid.uuid4().hex,
+            "issued_at": self._now_iso(),
+            "expires_at": self._expires((expires_in_minutes * 60_000) if expires_in_minutes else None),
+        }
+        body = {"envelope": env, "signature": self._sign(env)}
+        r = self._req("POST", "/v1/pay/transfer", body, idempotency=env["nonce"])
+        if r.get("status") != "settled":
+            raise VoidlyPayError(code=r.get("reason", "transfer_failed"), message=f"transfer failed: {r.get('reason')}", status=400, raw=r)
+        return r
+
+    def batch_transfer(self, items: Iterable[dict]) -> dict:
+        items_list = list(items)
+        if not items_list:
+            raise ValueError("batch_transfer: items empty")
+        env = {
+            "schema": "voidly-batch-transfer/v1",
+            "from_did": self.did,
+            "batch_id": uuid.uuid4().hex,
+            "items": [{"to_did": i["to"], "amount_micro": round(i["amount"] * MICRO_PER_CREDIT), "memo": i.get("memo")} for i in items_list],
+            "issued_at": self._now_iso(),
+            "expires_at": self._expires(),
+        }
+        body = {"envelope": env, "signature": self._sign(env)}
+        r = self._req("POST", "/v1/pay/batch", body, idempotency=env["batch_id"])
+        if r.get("status") != "settled":
+            raise VoidlyPayError(code=r.get("reason", "batch_failed"), message=f"batch failed: {r.get('reason')}", status=400, raw=r)
+        return r
+
+    def get_transfer(self, transfer_id: str) -> dict:
+        return self._req("GET", f"/v1/pay/transfer/{transfer_id}").get("transfer", {})
+
+    def history(self, did: str | None = None, limit: int | None = None, before: str | None = None) -> dict:
+        params = []
+        if limit:
+            params.append(f"limit={limit}")
+        if before:
+            params.append(f"before={requests.utils.quote(before)}")
+        qs = ("?" + "&".join(params)) if params else ""
+        return self._req("GET", f"/v1/pay/history/{did or self.did}{qs}")
+
+    # ─── Escrow ────────────────────────────────────────────────────────────
+
+    def open_escrow(self, to: str, amount: float, deadline_hours: int = 24, memo: str | None = None) -> dict:
+        from datetime import datetime, timezone, timedelta
+        dl = (datetime.now(timezone.utc) + timedelta(hours=deadline_hours)).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+        env = {
+            "schema": "voidly-escrow-open/v1",
+            "from_did": self.did,
+            "to_did": to,
+            "amount_micro": round(amount * MICRO_PER_CREDIT),
+            "memo": memo,
+            "deadline_at": dl,
+            "nonce": uuid.uuid4().hex,
+            "issued_at": self._now_iso(),
+            "expires_at": self._expires(),
+        }
+        return self._req("POST", "/v1/pay/escrow/open", {"envelope": env, "signature": self._sign(env)}, idempotency=env["nonce"])
+
+    def release_escrow(self, escrow_id: str) -> dict:
+        env = {
+            "schema": "voidly-escrow-release/v1",
+            "escrow_id": escrow_id,
+            "actor_did": self.did,
+            "nonce": uuid.uuid4().hex,
+            "issued_at": self._now_iso(),
+            "expires_at": self._expires(),
+        }
+        return self._req("POST", "/v1/pay/escrow/release", {"envelope": env, "signature": self._sign(env)})
+
+    def refund_escrow(self, escrow_id: str, reason: str | None = None) -> dict:
+        env = {
+            "schema": "voidly-escrow-refund/v1",
+            "escrow_id": escrow_id,
+            "actor_did": self.did,
+            "reason": reason,
+            "nonce": uuid.uuid4().hex,
+            "issued_at": self._now_iso(),
+            "expires_at": self._expires(),
+        }
+        return self._req("POST", "/v1/pay/escrow/refund", {"envelope": env, "signature": self._sign(env)})
+
+    # ─── x402 (server-side) ────────────────────────────────────────────────
+
+    def create_quote(
+        self,
+        resource: str,
+        amount: float,
+        recipient: str | None = None,
+        method: str | None = None,
+        description: str | None = None,
+        metadata: dict | None = None,
+        ttl_seconds: int | None = None,
+    ) -> dict:
+        env = {
+            "schema": "voidly-x402-quote/v1",
+            "server_did": self.did,
+            "resource": resource,
+            "amount_micro": round(amount * MICRO_PER_CREDIT),
+            "recipient_did": recipient or self.did,
+            "method": method,
+            "description": description,
+            "metadata": metadata,
+            "ttl_seconds": ttl_seconds,
+            "nonce": uuid.uuid4().hex,
+            "issued_at": self._now_iso(),
+            "expires_at": self._expires(),
+        }
+        return self._req("POST", "/v1/pay/x402/quote", {"envelope": env, "signature": self._sign(env)})
+
+    def verify_payment(self, quote_id: str, transfer_id: str | None = None, payment_header: str | None = None) -> dict:
+        env = {
+            "schema": "voidly-x402-verify/v1",
+            "server_did": self.did,
+            "quote_id": quote_id,
+            "transfer_id": transfer_id,
+            "payment_header": payment_header,
+            "nonce": uuid.uuid4().hex,
+            "issued_at": self._now_iso(),
+            "expires_at": self._expires(),
+        }
+        return self._req("POST", "/v1/pay/x402/verify", {"envelope": env, "signature": self._sign(env)})
+
+    # ─── x402 (client-side: pay-on-402) ────────────────────────────────────
+
+    def request_with_pay(
+        self,
+        method: str,
+        url: str,
+        max_amount: float | None = None,
+        **kwargs,
+    ) -> requests.Response:
+        """Fetch a URL; if it returns 402, parse the quote, transfer, retry."""
+        r = self.session.request(method, url, **kwargs)
+        if r.status_code != 402:
+            return r
+        try:
+            body = r.json()
+        except json.JSONDecodeError:
+            raise VoidlyPayError(code="x402_body_unparseable", message="Server returned 402 but no JSON body", status=402)
+        accept = (body.get("x402") or {}).get("accepts", [None])[0]
+        if not accept:
+            raise VoidlyPayError(code="x402_no_accept", message="Server 402 missing x402.accepts", status=402, raw=body)
+        if accept.get("scheme") != "voidly-credit":
+            raise VoidlyPayError(code="x402_unsupported_scheme", message=f"Unsupported scheme: {accept.get('scheme')}", status=402)
+        credits = accept["amount_micro"] / MICRO_PER_CREDIT
+        if max_amount is not None and credits > max_amount:
+            raise VoidlyPayError(code="x402_amount_exceeds_max", message=f"Quote price {credits} exceeds maxAmount {max_amount}", status=402)
+        t = self.transfer(to=accept["recipient_did"], amount=credits, memo=f"x402: {accept['resource']}")
+        headers = dict(kwargs.pop("headers", {}) or {})
+        headers["X-Payment"] = f"voidly-credit transfer_id={t['transfer_id']}; quote_id={accept['quote_id']}"
+        return self.session.request(method, url, headers=headers, **kwargs)
+
+    # ─── Webhooks ──────────────────────────────────────────────────────────
+
+    def subscribe_webhook(
+        self,
+        url: str,
+        events: list[str] | None = None,
+        did_filter: str | None = None,
+        description: str | None = None,
+    ) -> dict:
+        env = {
+            "schema": "voidly-webhook-subscribe/v1",
+            "did": self.did,
+            "url": url,
+            "event_filter": events,
+            "did_filter": did_filter,
+            "description": description,
+            "nonce": uuid.uuid4().hex,
+            "issued_at": self._now_iso(),
+            "expires_at": self._expires(),
+        }
+        return self._req("POST", "/v1/pay/webhooks", {"envelope": env, "signature": self._sign(env)}, idempotency=env["nonce"])
+
+    # ─── Network reads ─────────────────────────────────────────────────────
+
+    def health(self) -> dict: return self._req("GET", "/v1/pay/health")
+    def manifest(self) -> dict: return self._req("GET", "/v1/pay/manifest.json")
+    def stats(self) -> dict: return self._req("GET", "/v1/pay/stats")
+    def activity(self, limit: int = 50) -> dict: return self._req("GET", f"/v1/pay/activity?limit={limit}")
+    def leaderboard(self, metric: str = "earned_24h", limit: int = 25) -> dict:
+        return self._req("GET", f"/v1/pay/leaderboard?metric={metric}&limit={limit}")
+    def feed(self, since: str | None = None, limit: int = 50) -> dict:
+        qs = f"?limit={limit}" + (f"&since={requests.utils.quote(since)}" if since else "")
+        return self._req("GET", f"/v1/pay/feed{qs}")
+    def trust(self, did: str | None = None) -> dict:
+        return self._req("GET", f"/v1/pay/trust/{did or self.did}")
+
+
+# ─── Webhook signature verification ──────────────────────────────────────
+
+
+def verify_webhook_signature(
+    body: str | bytes,
+    signature_header: str,
+    secret: str,
+    tolerance_seconds: int = 300,
+) -> bool:
+    """Verify the X-Voidly-Signature header on a webhook delivery.
+
+    Returns True iff the HMAC matches AND the timestamp is within tolerance.
+    Constant-time compare via hmac.compare_digest.
+    """
+    if not signature_header.startswith("t="):
+        return False
+    parts = dict(p.split("=", 1) for p in signature_header.split(","))
+    try:
+        ts = int(parts["t"])
+    except (KeyError, ValueError):
+        return False
+    sig = parts.get("v1", "")
+    if abs(int(time.time()) - ts) > tolerance_seconds:
+        return False
+    body_bytes = body.encode("utf-8") if isinstance(body, str) else body
+    key_bytes = bytes.fromhex(secret)
+    msg = f"t={ts}.".encode() + body_bytes
+    expected = hmac.new(key_bytes, msg, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, sig)
+
+
+__all__ = [
+    "VoidlyPay",
+    "VoidlyPayError",
+    "verify_webhook_signature",
+    "did_from_pubkey",
+    "canonicalize",
+    "canonical_bytes",
+    "MICRO_PER_CREDIT",
+    "__version__",
+]

voidly_pay-0.1.1.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: voidly-pay
+Version: 0.1.1
+Summary: Voidly Pay SDK — agent-to-agent payments for AI agents
+Author-email: Voidly <team@voidly.ai>
+License: MIT
+Keywords: voidly,payments,ai-agents,x402,did,ed25519
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# voidly-pay (Python)
+
+> **The marketplace AI agents browse for paid HTTP services.** Pay any of 17+ paid endpoints for &lt;$0.01 using one Ed25519 keypair. List your own paid endpoint in 60 seconds. Settles in &lt;200ms via x402 + USDC on Base mainnet.
+
+[![PyPI version](https://img.shields.io/pypi/v/voidly-pay)](https://pypi.org/project/voidly-pay/)
+[![x402](https://img.shields.io/badge/x402-canonical%20v2-blue)](https://www.x402.org)
+[![vault](https://img.shields.io/badge/vault-Sourcify%20verified-emerald)](https://repo.sourcify.dev/contracts/full_match/8453/0xb592512932a7b354969bb48039c2dc7ad6ad1c12/)
+
+```bash
+pip install voidly-pay
+```
+
+## 30-second tour
+
+```python
+from voidly_pay import VoidlyPay
+
+pay = VoidlyPay()                              # mints + persists keypair
+print("DID:", pay.did)                          # did:voidly:...
+pay.faucet()                                    # 10 free credits
+
+# Browse the marketplace — 17 paid endpoints + N third-party listings
+mp = pay.request("GET", "/v1/pay/marketplace").json()
+for item in mp["items"][:5]:
+    print(f"{item['name']:40s} ${item['pricing']['amount_usdc']}")
+
+# Pay any paid endpoint via auto-x402
+r = pay.request_with_pay(
+    "GET",
+    "https://api.voidly.ai/v1/pay/wiki?title=Alan%20Turing",
+    max_amount=0.005,
+)
+receipt = r.json()
+print(receipt["extract"][:200])
+```
+
+## Pay anything that returns 402
+
+```python
+# Universal x402 client — handles 402 → quote → settle → retry
+r = pay.request_with_pay(
+    "POST",
+    "https://api.voidly.ai/v1/pay/extract",
+    json={"url": "https://arxiv.org/pdf/2507.14183.pdf"},
+    max_amount=0.01,
+)
+print(r.json()["text_length"])
+```
+
+## List your own paid endpoint
+
+```python
+pay.create_listing(
+    name="My Paid API",
+    tagline="Pay 1¢ for X, get Y signed.",
+    url="https://my-api.example.com/expensive",
+    amount_usdc=0.01,
+    category="data",
+    tags=["json", "agents"],
+)
+# Now appears at /v1/pay/marketplace, every Voidly-aware agent sees it.
+```
+
+Or browser-only (no install): [voidly.ai/pay/list-your-service](https://voidly.ai/pay/list-your-service).
+
+## Run a paid endpoint (FastAPI)
+
+```python
+from fastapi import FastAPI, Depends
+from voidly_pay import VoidlyPay
+from voidly_pay.middleware import fastapi_x402
+
+app = FastAPI()
+pay = VoidlyPay()
+
+# Charge $0.01 per request — settles atomically with the response.
+@app.get("/expensive", dependencies=[Depends(fastapi_x402(pay, amount=0.01))])
+def expensive():
+    return {"data": "the goods"}
+```
+
+Flask:
+
+```python
+from flask import Flask
+from voidly_pay import VoidlyPay
+from voidly_pay.middleware import flask_x402
+
+app = Flask(__name__)
+pay = VoidlyPay()
+
+@app.route("/expensive")
+@flask_x402(pay, amount=0.01)
+def expensive():
+    return {"data": "the goods"}
+```
+
+## What you can do
+
+| Primitive | Method |
+|---|---|
+| **Marketplace** | `pay.create_listing(...)`, `pay.list_listings()`, `pay.get_listing(id)` |
+| **Pay any URL** | `pay.request_with_pay(method, url, max_amount=...)` |
+| **Direct transfer** | `pay.transfer(to, amount)` |
+| **Batch transfer** | `pay.batch_transfer([{...}, ...])` |
+| **Escrow** | `pay.open_escrow(to, amount, deadline_hours)` |
+| **Streams (per-token billing)** | `pay.open_stream(...)`, `pay.meter_stream(...)`, `pay.finalize_stream(...)` |
+| **Subscriptions** | `pay.subscribe(...)`, `pay.cancel_subscription(...)` |
+| **x402 server-side quote** | `pay.create_quote(resource, amount)` |
+| **x402 server-side verify** | `pay.verify_payment(quote_id, transfer_id)` |
+| **Webhooks** | `pay.subscribe_webhook(url, events=[...])` |
+| **Trust check** | `pay.health_check()` (6-check report incl. on-chain vault read) |
+
+## What's in the marketplace today (Voidly's 17 paid endpoints)
+
+| Endpoint | Price | What it does |
+|---|---|---|
+| `voidly_hash` | $0.001 | SHA-256/512 + signed receipt |
+| `voidly_timestamp` | $0.001 | Proof-of-existence (OpenTimestamps-style) |
+| `voidly_random` | $0.001 | Signed CSPRNG bytes |
+| `voidly_qr` | $0.001 | QR-code PNG of any text/URL |
+| `voidly_wiki` | $0.001 | Wikipedia summary + signed citation |
+| `voidly_exchange` | $0.001 | Fiat/crypto exchange rates |
+| `voidly_markdown` | $0.001 | HTML → clean markdown (10x reduction) |
+| `voidly_meta` | $0.001 | URL metadata (og + title + canonical) |
+| `voidly_extract` | $0.01 | PDF/document → plain text |
+| `voidly_scrape` | $0.01 | Fetch any URL + Voidly-signed receipt |
+| `voidly_fetch` | $0.05 | Country-pinned fetch via 37+ probe network |
+| `probe_attest` | $0.005 | Multi-vantage signed reachability proof |
+| `forecast_pro` | $0.01 | 30-day country-shutdown risk forecast |
+| `claim_verify_pro` | $0.005 | Evidence-backed verification of claims |
+| `incident_summary_pro` | $0.005 | Plain-English summary of an incident |
+| `agent_discover_pro` | $0.005 | Premium ranked agent search |
+| `incidents_export_pro` | $0.05 | Bulk export (high limit, no rate cap) |
+
+Plus N third-party listings registered self-serve at [voidly.ai/pay/list-your-service](https://voidly.ai/pay/list-your-service).
+
+Live machine-readable catalog: [api.voidly.ai/v1/pay/marketplace](https://api.voidly.ai/v1/pay/marketplace).
+
+## Configuration
+
+```python
+pay = VoidlyPay(
+    api_url="https://api.voidly.ai",
+    secret_key=existing_key,                # bring your own
+    storage_path="~/.my-keys/voidly.json",
+    default_expiry_minutes=30,
+)
+```
+
+## Webhook verification
+
+```python
+from voidly_pay import verify_webhook_signature
+
+ok = verify_webhook_signature(
+    body=raw_body,
+    signature_header=headers["X-Voidly-Signature"],
+    secret=os.environ["VOIDLY_WEBHOOK_SECRET"],
+)
+```
+
+## Why agents use this
+
+| Problem | Voidly Pay solves it |
+|---|---|
+| **Need to add payment to your agent service** | x402 middleware ships for FastAPI, Flask, any web-fetch handler |
+| **Need to discover paid services** | One install → 17 endpoints + open marketplace listings |
+| **Don't want to manage 10 API keys** | One Ed25519 keypair, one wallet, every paid endpoint works |
+| **Don't trust the agent's payment claims** | Every receipt is Ed25519-signed by Voidly. Verifiable offline. |
+| **Need country-attested fetch** | 37+ probe network, signed (URL, country, ASN, probe-DID) |
+
+## Honest disclosure
+
+The Voidly Pay vault on Base mainnet (`0xb592512932a7b354969bb48039c2dc7ad6ad1c12`, [Sourcify-verified](https://repo.sourcify.dev/contracts/full_match/8453/0xb592512932a7b354969bb48039c2dc7ad6ad1c12/)) currently holds **$4 USDC**. We have approximately zero sustained external paying users yet. Live reserves at [voidly.ai/pay/proof](https://voidly.ai/pay/proof).
+
+We opened the marketplace before the demand exists because we believe agent adoption is gated on discoverability, not on payment-rail UX.
+
+## Framework adapters (use these for higher-level integration)
+
+- **LangChain**: `pip install voidly-pay-langchain`
+- **CrewAI**: `pip install voidly-pay-crewai`
+- **Pydantic AI**: `pip install voidly-pay-pydantic-ai`
+- **AutoGen**: `pip install voidly-pay-autogen`
+- **LlamaIndex**: `pip install voidly-pay-llamaindex`
+
+## Links
+
+- [Marketplace JSON](https://api.voidly.ai/v1/pay/marketplace)
+- [/pay/install](https://voidly.ai/pay/install) — one-click MCP install (any client)
+- [/pay/marketplace](https://voidly.ai/pay/marketplace) — visual browse
+- [/pay/list-your-service](https://voidly.ai/pay/list-your-service) — list in 60s
+- [/pay/claim](https://voidly.ai/pay/claim) — free 10-credit faucet
+- [/pay/proof](https://voidly.ai/pay/proof) — live reserves dashboard
+- [/pay/for-builders](https://voidly.ai/pay/for-builders) — every middleware + adapter
+- [Voidly Pay landing](https://voidly.ai/pay)
+
+## Keywords
+
+x402 · agent payments · python sdk · usdc · base mainnet · signed receipts · agent marketplace · pay per call · micropayments · fastapi x402 · flask x402 · langchain agent payments · crewai payments · llamaindex tools · pydantic-ai tools · autogen extensions
+
+## License
+
+MIT

voidly_pay-0.1.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+voidly_pay/__init__.py,sha256=lFZnWORvIOJGwTusTUDWrPTjHhWySKygETDMr_r66Ak,20654
+voidly_pay-0.1.1.dist-info/METADATA,sha256=ZKJfhV504fLEI46LdkXyLAicnrblBWZ1fhPqRLOzQYs,8462
+voidly_pay-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+voidly_pay-0.1.1.dist-info/top_level.txt,sha256=hlJmPLM5vAsdroCP3-ZkciqAng-l9IrpnRP60-L_VEM,11
+voidly_pay-0.1.1.dist-info/RECORD,,

voidly_pay-0.1.1.dist-info/WHEEL

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

voidly_pay-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+voidly_pay