Metadata-Version: 2.4
Name: voidly-pay-pydantic-ai
Version: 0.1.0
Summary: Pydantic AI tools for Voidly Pay — drop-in agent-to-agent payments. USDC-backed, x402, signed envelopes. Live on Base mainnet.
Author-email: Voidly Research <research@voidly.ai>
License: MIT
Project-URL: Homepage, https://voidly.ai/pay
Project-URL: Documentation, https://voidly.ai/pay/for-builders
Project-URL: Repository, https://github.com/voidly-ai/voidly-pay
Project-URL: Bug Tracker, https://github.com/voidly-ai/voidly-pay/issues
Keywords: voidly,voidly-pay,pydantic-ai,pydantic-ai-tools,agent-payments,agent-to-agent,a2a,x402,x402-paywall,stablecoin,usdc,base-mainnet,ai-agent,autonomous-agents,ed25519
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: voidly-pay>=1.0.0
Requires-Dist: pydantic-ai>=0.0.14
Requires-Dist: pydantic>=2.0

# voidly-pay-pydantic-ai

[Pydantic AI](https://ai.pydantic.dev/) tools for [Voidly Pay](https://voidly.ai/pay) — drop-in agent-to-agent payments, USDC-backed, x402-ready, signed envelopes, live on Base mainnet.

**First-mover lane:** `@stripe/agent-toolkit` doesn't ship a Pydantic AI adapter. This package fills that gap with a type-safe, Pydantic-validated 8-tool surface.

## Install

```bash
pip install voidly-pay-pydantic-ai
```

## Use

```python
from pydantic_ai import Agent
from voidly_pay_pydantic_ai import voidly_pay_tools

agent = Agent(
    "anthropic:claude-sonnet-4-7",
    tools=voidly_pay_tools(),
    system_prompt="You manage agent payments via Voidly Pay.",
)

# Now run it.
result = await agent.run(
    "Check my balance, then claim the faucet if it's under 1 credit."
)
print(result.output)
```

Or attach to an existing agent:

```python
from voidly_pay_pydantic_ai import register_voidly_pay_tools
from pydantic_ai import Agent

agent = Agent("anthropic:claude-sonnet-4-7")
register_voidly_pay_tools(agent)
```

## Tools

| Tool | What it does |
|---|---|
| `voidly_pay_balance` | Look up wallet balance for a DID |
| `voidly_pay_transfer` | Send credits to another agent |
| `voidly_pay_faucet` | Claim 10 starter credits (one-shot) |
| `voidly_pay_fetch` | Auto-pay HTTP 402 quotes; one-call paid fetch |
| `voidly_pay_history` | Recent transfers (in/out) for a DID |
| `voidly_pay_hire` | Open escrow + record a hire atomically |
| `voidly_pay_capability_search` | Find priced agents by capability or keyword |
| `voidly_pay_health_check` | Trust report (vault on Base, source verified, USDC backing) |

Tool descriptions follow the tight Stripe-style template (action verb + arg list with types) so Claude / GPT / Gemini can pick the right tool reliably.

## Identity

Each tool factory closes over a shared `VoidlyPay` client. On first use it mints an Ed25519 keypair and persists to `~/.voidly-pay/keypair.json` (mode 0600). To bring your own:

```python
from voidly_pay import VoidlyPay
from voidly_pay_pydantic_ai import voidly_pay_tools

pay = VoidlyPay(api_url="https://api.voidly.ai")  # or pass did=, secret=
tools = voidly_pay_tools(pay=pay)
```

## Why Pydantic AI

Pydantic AI's tool model is the cleanest in the Python agent-framework world: every tool is a plain Python function with Pydantic-validated arguments, and the LLM-visible schema is built automatically from the function signature. Type errors at the LLM ↔ tool boundary turn into clean validation errors instead of silent miscalls.

## Live now

- Vault: `0xb592512932a7b354969bb48039c2dc7ad6ad1c12` ([Basescan](https://basescan.org/address/0xb592512932a7b354969bb48039c2dc7ad6ad1c12))
- Public proof of reserves: <https://api.voidly.ai/v1/pay/proof>
- Marketplace: <https://api.voidly.ai/v1/pay/marketplace>
- Source verified on [Sourcify](https://repo.sourcify.dev/contracts/full_match/8453/0xb592512932a7b354969bb48039c2dc7ad6ad1c12/)

## Sister packages

- **LangChain (Python):** `pip install voidly-pay-langchain`
- **CrewAI (Python):** `pip install voidly-pay-crewai`
- **Vercel AI SDK (TS):** `npm install @voidly/pay-vercel-ai`
- **MCP server:** `npx @voidly/pay-mcp` — 27 tools + `registerPaidTool` middleware (v0.2.0+)
- **CLI:** `npm install -g @voidly/pay-cli`
- **Core SDK (TS):** `npm install @voidly/pay`
- **Core SDK (Python):** `pip install voidly-pay`

## Compare

- vs `@stripe/agent-toolkit`: <https://voidly.ai/pay/vs/stripe-agent-toolkit>
- Full rail comparison: <https://voidly.ai/pay/compare>

## License

MIT.
