voidly-pay 0.1.1__tar.gz

voidly_pay-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,204 @@
+# voidly-pay (Python)
+
+> **The marketplace AI agents browse for paid HTTP services.** Pay any of 17+ paid endpoints for <$0.01 using one Ed25519 keypair. List your own paid endpoint in 60 seconds. Settles in <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/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "voidly-pay"
+version = "0.1.1"
+description = "Voidly Pay SDK — agent-to-agent payments for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Voidly", email = "team@voidly.ai" }]
+keywords = ["voidly", "payments", "ai-agents", "x402", "did", "ed25519"]
+dependencies = [
+  "pynacl>=1.5.0",
+  "requests>=2.31.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-mock>=3.10", "responses>=0.23"]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["voidly_pay"]

voidly_pay-0.1.1/setup.cfg

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

voidly_pay-0.1.1/tests/test_sdk.py

@@ -0,0 +1,167 @@
+"""Smoke tests for the Python voidly-pay SDK.
+
+Exercises envelope shape, signing, persistence, webhook signature verify.
+Real settlement is tested in the worker repo.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import nacl.signing
+
+from voidly_pay import (
+    VoidlyPay,
+    VoidlyPayError,
+    canonical_bytes,
+    canonicalize,
+    did_from_pubkey,
+    verify_webhook_signature,
+)
+
+
+def fake_session(routes: dict):
+    """Build a requests.Session mock that returns canned responses by route."""
+    sess = mock.Mock()
+    captured = []
+
+    def request(method, url, **kwargs):
+        captured.append({"method": method.upper(), "url": url, "json_body": kwargs.get("json"), "headers": kwargs.get("headers", {})})
+        from urllib.parse import urlparse
+        path = urlparse(url).path
+        key = f"{method.upper()} {path}"
+        if key not in routes and path not in routes:
+            resp = mock.Mock()
+            resp.status_code = 404
+            resp.ok = False
+            resp.text = json.dumps({"error": {"code": "no_route", "message": f"no fake for {key}"}})
+            resp.json = lambda: json.loads(resp.text)
+            return resp
+        return routes.get(key) or routes[path]
+
+    sess.request = mock.Mock(side_effect=request)
+    return sess, captured
+
+
+def resp_json(payload, status=200):
+    r = mock.Mock()
+    r.status_code = status
+    r.ok = 200 <= status < 300
+    r.text = json.dumps(payload)
+    r.json = lambda: payload
+    return r
+
+
+class CanonicalTests(unittest.TestCase):
+    def test_sorts_keys(self):
+        self.assertEqual(canonicalize({"b": 1, "a": 2}), '{"a":2,"b":1}')
+
+    def test_omits_none(self):
+        self.assertEqual(canonicalize({"a": 1, "b": None, "c": 2}), '{"a":1,"c":2}')
+
+    def test_nested(self):
+        self.assertEqual(canonicalize({"x": {"z": 1, "y": 2}}), '{"x":{"y":2,"z":1}}')
+
+    def test_parity_regardless_of_order(self):
+        a = canonical_bytes({"x": 1, "y": 2, "z": 3})
+        b = canonical_bytes({"z": 3, "x": 1, "y": 2})
+        self.assertEqual(a, b)
+
+
+class DIDTests(unittest.TestCase):
+    def test_did_format(self):
+        kp = nacl.signing.SigningKey.generate()
+        pk = bytes(kp.verify_key)
+        did = did_from_pubkey(pk)
+        self.assertTrue(did.startswith("did:voidly:"))
+
+
+class ConstructionTests(unittest.TestCase):
+    def test_persists_and_loads_keypair(self):
+        with mock.patch("voidly_pay._default_storage_path", return_value=Path(self._tmp())):
+            sess, _ = fake_session({})
+            p1 = VoidlyPay(api_url="http://x", session=sess)
+            p2 = VoidlyPay(api_url="http://x", session=sess)
+            self.assertEqual(p1.did, p2.did)
+
+    def test_explicit_secret_key(self):
+        kp = nacl.signing.SigningKey.generate()
+        sk = bytes(kp._signing_key)
+        sess, _ = fake_session({})
+        pay = VoidlyPay(api_url="http://x", secret_key=sk, session=sess)
+        self.assertEqual(pay.did, did_from_pubkey(bytes(kp.verify_key)))
+
+    def _tmp(self):
+        import tempfile
+        return tempfile.NamedTemporaryFile(delete=False).name
+
+
+class TransferTests(unittest.TestCase):
+    def test_transfer_envelope_shape(self):
+        sess, captured = fake_session({
+            "POST /v1/pay/wallet": resp_json({"wallet": {"did": "x"}}),
+            "POST /v1/pay/transfer": resp_json({
+                "schema": "voidly-pay-receipt/v1",
+                "status": "settled",
+                "transfer_id": "t-1",
+                "envelope_hash": "h",
+                "settled_at": "2026-04-26T00:00:00Z",
+                "sender_new_balance_micro": 0,
+                "recipient_new_balance_micro": 1_000_000,
+            }),
+        })
+        kp = nacl.signing.SigningKey.generate()
+        pay = VoidlyPay(api_url="http://x.example", secret_key=bytes(kp._signing_key), session=sess)
+        r = pay.transfer(to="did:voidly:bob", amount=1.0, memo="hi")
+        self.assertEqual(r["transfer_id"], "t-1")
+        # Find the transfer call
+        tcall = next(c for c in captured if c["url"].endswith("/v1/pay/transfer"))
+        env = tcall["json_body"]["envelope"]
+        self.assertEqual(env["schema"], "voidly-credit-transfer/v1")
+        self.assertEqual(env["from_did"], pay.did)
+        self.assertEqual(env["to_did"], "did:voidly:bob")
+        self.assertEqual(env["amount_micro"], 1_000_000)
+        self.assertEqual(env["memo"], "hi")
+        self.assertIsInstance(tcall["json_body"]["signature"], str)
+
+    def test_transfer_raises_on_failure(self):
+        sess, _ = fake_session({
+            "POST /v1/pay/wallet": resp_json({"wallet": {}}),
+            "POST /v1/pay/transfer": resp_json({"error": {"code": "insufficient_balance", "message": "no funds"}}, status=402),
+        })
+        kp = nacl.signing.SigningKey.generate()
+        pay = VoidlyPay(api_url="http://x.example", secret_key=bytes(kp._signing_key), session=sess)
+        with self.assertRaises(VoidlyPayError) as ctx:
+            pay.transfer(to="did:voidly:bob", amount=1.0)
+        self.assertEqual(ctx.exception.code, "insufficient_balance")
+
+
+class WebhookSignatureTests(unittest.TestCase):
+    def test_valid_signature(self):
+        secret = "deadbeef" * 8
+        body = '{"foo":1}'
+        ts = int(time.time())
+        sig = hmac.new(bytes.fromhex(secret), f"t={ts}.{body}".encode(), hashlib.sha256).hexdigest()
+        self.assertTrue(verify_webhook_signature(body, f"t={ts},v1={sig}", secret))
+
+    def test_tampered_rejected(self):
+        secret = "deadbeef" * 8
+        ts = int(time.time())
+        self.assertFalse(verify_webhook_signature("a", f"t={ts},v1=" + "0" * 64, secret))
+
+    def test_stale_rejected(self):
+        secret = "deadbeef" * 8
+        old = int(time.time()) - 3600
+        sig = hmac.new(bytes.fromhex(secret), f"t={old}.x".encode(), hashlib.sha256).hexdigest()
+        self.assertFalse(verify_webhook_signature("x", f"t={old},v1={sig}", secret))
+
+
+if __name__ == "__main__":
+    unittest.main()

voidly_pay-0.1.1/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/voidly_pay.egg-info/PKG-INFO

@@ -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/voidly_pay.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+tests/test_sdk.py
+voidly_pay/__init__.py
+voidly_pay.egg-info/PKG-INFO
+voidly_pay.egg-info/SOURCES.txt
+voidly_pay.egg-info/dependency_links.txt
+voidly_pay.egg-info/requires.txt
+voidly_pay.egg-info/top_level.txt

voidly_pay-0.1.1/voidly_pay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

voidly_pay-0.1.1/voidly_pay.egg-info/requires.txt

@@ -0,0 +1,7 @@
+pynacl>=1.5.0
+requests>=2.31.0
+
+[dev]
+pytest>=7.0
+pytest-mock>=3.10
+responses>=0.23

voidly_pay-0.1.1/voidly_pay.egg-info/top_level.txt

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