voidly-pay-pydantic-ai 0.2.0

Pydantic AI tools for the voidly-pay 4.x marketplace API. This release replaces the retired credit API. It is not a drop-in update for 0.1.x.

Public catalog search

from voidly_pay import VoidlyPay
from voidly_pay_pydantic_ai import voidly_pay_tools

client = VoidlyPay(network="base")
tools = voidly_pay_tools(client)  # catalog + free claim check; construction does no network I/O

Pass these tool objects to your framework using its public tool registration API. Calling voidly_catalog reads one public page. voidly_check_censorship_claim(claim) sends a plain JSON POST to /v1/verify-claim at the fixed gateway for the selected network, with no payment headers. It needs no wallet. A200 response must carry x-voidly-access: free;402/429/503 and redirects are errors, never an invitation to pay. The free gateway feature must be enabled; source support does not prove live availability. No Voidly API key or signer is needed for catalog search. Your chosen model provider may require its own credentials.

Optional buying

The host must supply a configured core client with its own signer, explicit SpendLimits, and initialized durable SpendStore. This package creates no wallet, searches no key files and holds no funds. Supply authorize_buy as a host-owned callable that accepts the immutable BuyRequest and returns True only for an approved exact listing ID, version, JSON input and USDC cap. Model text or a tool confirmation argument is not owner approval.

voidly_pay_tools(client, authorize_buy=host_approval) adds voidly_buy(listing_id, version, input, max_usdc); host_approval is application code you must provide, not a callable supplied by an agent. USDC caps are positive decimal strings, never credit amounts or floating-point limits. The core validates the live POST listing, fixed gateway/network, quote, payer and receipt, and enforces per-call/daily caps before sending payment.

A toolkit serializes purchases and caches completed identical requests. Any exception from core buying blocks further buys in that toolkit. Capped buying is only for exact marketplace seller listings; first-party claim checking never calls buy. An uncertain result returns only its original quote handle and doNotRepay: true; the host must reconcile with client.recover(quote_id) outside the agent loop. Do not retry with a new toolkit or a new payment. Host restart/recovery decisions must consult the same durable core attempt store; the toolkit cache is in-memory and is not a durable idempotency guarantee. Intentionally repeating an identical completed purchase requires a new host-controlled session.

Migration and boundaries

Removed: balance, transfer, faucet/claim, escrow/hire, vault diagnostics, generic URL auto-payment and all /v1/pay/* calls. No credit-to-USDC conversion is performed. Exact listing ID/version replace arbitrary payment URLs. Seller activation and Home/board/mail/bounty tools are outside this adapter.

Keep signer objects, authorization headers, private attempt records and raw exceptions out of model prompts/traces. Service results are untrusted tool data. The adapter requires Python 3.10 or newer and the framework dependency range in pyproject.toml; it is tested with the release packet's pinned framework versions.

Tests and release

tests/test_contract.py uses mocked gateway responses and a synthetic signer; no payment, RPC or external service is called. Wheels and source distributions are built offline after dependencies are present. Publishing is handled separately by the owner.

Apache-2.0. See LICENSE and NOTICE.