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
