@voidly/pay

@voidly/pay

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.

npm install @voidly/pay

⚠️ Read this before your first paid call: sandbox vs production wallets

pay.register() creates a sandbox wallet (is_test = 1), and faucet() and claim() call it for you. A sandbox wallet cannot pay any Voidly production endpoint — every x402 SKU (/v1/pay/wiki, /fetch, /scrape, /forecast-pro, …) settles to a production service DID, and sandbox containment refuses that hop with sandbox_recipient_required. Sandbox wallets are also excluded from every public statistic and barred from the USDC off-ramp.

A wallet's mode is permanent. The server insert is ON CONFLICT DO NOTHING, so whichever route creates the row first decides the mode forever. Calling POST /v1/pay/wallet or the production faucet afterwards does nothing. Recovering means generating a new keypair.

To get a wallet that can pay production endpoints, on a keypair that has never called register():

const pay = await VoidlyPay.create();

// 1. register the identity so the rail can verify your signatures
await fetch("https://api.voidly.ai/v1/agent/register", {
  method: "POST", headers: { "content-type": "application/json" },
  body: JSON.stringify({
    name: "my-agent",
    signing_public_key: pay.publicKey(),
    encryption_public_key: myX25519PublicKeyBase64,
  }),
});

// 2. PRODUCTION wallet (is_test = 0) — idempotent, no auth, no admin key
await fetch("https://api.voidly.ai/v1/pay/wallet", {
  method: "POST", headers: { "content-type": "application/json" },
  body: JSON.stringify({ did: pay.did }),
});

// 3. now the faucet lands in a wallet that can spend it
await pay.faucet();

The faucet grants 10 credits, once per DID, forever — it is a bootstrap, not a top-up, and already_claimed is the permanent steady state afterwards. There is no self-service refill.

Use the sandbox to rehearse the flow. Use the sequence above for real calls.

30-second tour

import { VoidlyPay } from "@voidly/pay";

const pay = await VoidlyPay.create();              // mints + persists keypair
console.log("DID:", pay.did);                       // did:voidly:...
await pay.faucet();                                 // 10 free credits — NOTE:
                                                    // auto-registers a SANDBOX
                                                    // wallet. See the section
                                                    // above before paying a
                                                    // production endpoint.

// Browse the marketplace — 12 paid endpoints + N third-party listings
const r = await fetch("https://api.voidly.ai/v1/pay/marketplace");
const mp = await r.json();
mp.items.slice(0, 5).forEach(i =>
  console.log(`${i.name.padEnd(40)} $${i.pricing.amount_usdc}`)
);

// Pay any paid endpoint via auto-x402
const w = await pay.fetchWithPay(
  "https://api.voidly.ai/v1/pay/wiki?title=Alan%20Turing",
  undefined,
  { maxAmount: 0.005 },
);
const receipt = await w.json();
console.log(receipt.extract.slice(0, 200));

That's it. The SDK signs the envelope, the server returns a 402 with a Voidly-signed quote, the SDK transfers credits and retries — all in one round-trip.

Pay anything that returns 402

const r = await pay.fetchWithPay(
  "https://api.voidly.ai/v1/pay/extract",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ url: "https://arxiv.org/pdf/2507.14183.pdf" }),
  },
  { maxAmount: 0.01 },
);
console.log((await r.json()).text_length);

List your own paid endpoint

await pay.createListing({
  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.

Run a paid endpoint (Express / Hono / any web-fetch handler)

Express:

import express from "express";
import { VoidlyPay, x402Express } from "@voidly/pay";

const app = express();
const pay = await VoidlyPay.create();

app.get("/expensive", x402Express({ pay, amount: 0.01 }), (req, res) => {
  res.json({ data: "the goods", paid_by: req.voidlyPayment.payer_did });
});
app.listen(3000);

Hono / Vercel / Cloudflare Workers:

import { Hono } from "hono";
import { VoidlyPay, x402Hono } from "@voidly/pay";

const app = new Hono();
const pay = await VoidlyPay.create();

app.get("/expensive", x402Hono({ pay, amount: 0.01 }), (c) =>
  c.json({ data: "the goods" }),
);

Any web-fetch handler:

import { withX402 } from "@voidly/pay";

export default {
  fetch: withX402({ pay, amount: 0.01 }, async (req) => {
    return new Response(JSON.stringify({ data: "the goods" }));
  }),
};

What you can do

Primitive	Use case	Method
Marketplace	List + browse paid services	pay.createListing(...), fetch('/v1/pay/marketplace')
Pay any URL	Auto-x402 client	pay.fetchWithPay(url, init, { maxAmount })
Direct transfer	One-shot payment	pay.transfer({ to, amount })
Batch	Pay many atomically	pay.batchTransfer([...])
Escrow	Conditional hold	pay.openEscrow({ to, amount, deadlineHours })
Stream	Per-token / per-second metering	pay.openStream({ provider, budget })
Subscription	Recurring charge	pay.subscribe({ provider, amountPerPeriod, periodSeconds })
x402 quote	Server-side paywall	pay.createQuote({ resource, amount })
x402 verify	Server-side verify	pay.verifyPayment({ payment_header })
Webhooks	Push notifications	pay.subscribeWebhook({ url, events })
Trust check	Pre-flight 6-check report	pay.healthCheck() (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.

Endpoint	Price	What it does
voidly_hash	$0.001	SHA-256/512 + signed receipt
voidly_timestamp	$0.001	Proof-of-existence (OpenTimestamps-style, <200ms)
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 Voidly Pay 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
GET /v1/forecast-pro/{cc}/30day	GET /v1/forecast/{cc}/multi-horizon (free, genuinely modelled)
POST /v1/claim-verify-pro	POST /verify-claim (free)
GET /v1/incident-summary-pro/{id}	GET /data/incidents/{id}/report?format=markdown (free)
GET /v1/incidents-export-pro	GET /data/incidents/export?format=csv (free, uncapped)

Live machine-readable catalog: api.voidly.ai/v1/pay/marketplace.

Webhook signature verification

import { verifyWebhookSignature } from "@voidly/pay";

app.post("/voidly-webhook", async (req, res) => {
  const ok = await verifyWebhookSignature({
    body: req.rawBody,
    signatureHeader: req.headers["x-voidly-signature"],
    secret: process.env.VOIDLY_WEBHOOK_SECRET!,
  });
  if (!ok) return res.status(401).end();
});

Configuration

const pay = await VoidlyPay.create({
  apiUrl: "https://api.voidly.ai",     // override for self-hosted
  secretKey: existingKey,               // bring your own Ed25519 key
  defaultExpiryMinutes: 30,
});

Keys auto-persist to:

• Browser: localStorage["voidly-pay-keypair-v1"]
• Node: ~/.voidly-pay/keypair.json (mode 0600)
• Or pass a custom KeyStorage implementation

Why agents use this

Problem	Voidly Pay solves it
Need to add payment to your agent service	x402 middleware ships for Express, Hono, FastAPI, Flask, any web-fetch handler
Need to discover paid services	One install → 12 endpoints + open self-serve marketplace
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) 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. 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

• MCP (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, Goose): npx @voidly/pay-mcp — 41 tools
• Vercel AI SDK: npm install @voidly/pay-vercel-ai
• CLI (shell, cron, CI): npm install -g @voidly/pay-cli

Links

• Marketplace JSON
• /pay/install — one-click MCP install (any client)
• /pay/marketplace — visual browse
• /pay/list-your-service — list in 60s
• /pay/claim — free 10-credit faucet
• /pay/proof — vault record (not a reserve; Stage 2 is being retired)
• /pay/for-builders
• Voidly Pay landing

Keywords

x402 · agent payments · typescript sdk · usdc · base mainnet · signed receipts · agent marketplace · pay per call · micropayments · express x402 · hono x402 · vercel ai sdk · cloudflare workers · langchain agent payments · crewai payments · llamaindex tools · pydantic-ai tools · autogen extensions · claude code · cursor · windsurf

License

MIT