Metadata-Version: 2.4
Name: voidly-pay
Version: 3.0.0
Summary: voidpay SDK — zero-value internal test-credit tools for agent-to-agent transfers and x402 integration. Credits are not backed or redeemable.
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/0xd25d3c6f32886b65356cc5c700382a8a02d84df5/)

```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 — 12 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(payment_header=header, payer_proof=proof, expected_resource=resource, expected_method=method, min_amount=price, expected_metadata=metadata)` |
| **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 12 paid endpoints)

Voidly does not sell its censorship data. The dataset is free and CC BY 4.0.
Every endpoint below charges for compute, or for an Ed25519 signature over data
that is itself free — never for the observatory. Five SKUs that failed that test
were retired on 2026-08-04 and now return HTTP 410 naming their free
replacement; see [voidly.ai/pay/changelog](https://voidly.ai/pay/changelog).

| 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 |
| `probe_attest` | $0.005 | Ed25519 attestation over probe reachability data. The data is free at `/v1/probe/domain/{host}`; the charge is the signature. |
| `agent_discover_pro` | $0.005 | Ranked search over the voidpay agent registry (not observatory data). Free 20-result search at `/v1/agent/discover`. |

Retired 2026-08-04 — these now return **HTTP 410 Gone** with the free
replacement URL in the body. Do not route to them:

| Retired | Free replacement |
|---|---|
| `voidly_fetch` / `POST /v1/pay/fetch` | `voidly_scrape` — the country-pinning was never implemented, so every call was already a Cloudflare-edge fetch |
| `forecast_pro` | `GET /v1/forecast/{cc}/multi-horizon` (free, genuinely modelled) |
| `claim_verify_pro` | `POST /verify-claim` (free) |
| `incident_summary_pro` | `GET /data/incidents/{id}/report?format=markdown` (free) |
| `incidents_export_pro` | `GET /data/incidents/export?format=csv` (free, uncapped) |

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 | voidpay 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 → 12 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 censorship data** | It is free. `GET /data/incidents/export?format=csv`, CC BY 4.0, no wallet, no key. Voidly does not sell it. |

## Honest disclosure

**Stage 2 is being retired** (decided 2026-08-04). Credits are an internal accounting unit: not backed, not redeemable, no off-ramp. The vault on Base mainnet (`0xd25d3c6f32886b65356cc5c700382a8a02d84df5`, [Sourcify-verified](https://repo.sourcify.dev/contracts/full_match/8453/0xd25d3c6f32886b65356cc5c700382a8a02d84df5/)) holds 4.10 USDC, has never settled a payment on the canonical x402 path, and its deployed documentation claimed governance could not unilaterally move funds — which the code does not enforce. It stays on-chain as a public record at [voidly.ai/pay/proof](https://voidly.ai/pay/proof). We have approximately zero sustained external paying users.

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) — vault record (not a reserve; Stage 2 is being retired)
- [/pay/for-builders](https://voidly.ai/pay/for-builders) — every middleware + adapter
- [voidpay 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
