Metadata-Version: 2.4
Name: paybond-kit
Version: 0.12.16
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: blake3>=1.0,<2
Requires-Dist: cryptography>=48.0,<49
Requires-Dist: ecdsa>=0.19,<1
Requires-Dist: httpx>=0.27,<1
Requires-Dist: jsonschema>=4.26
Requires-Dist: pycryptodome>=3.21,<4
Requires-Dist: claude-agent-sdk>=0.2.100 ; extra == 'claude-agents'
Requires-Dist: crewai>=1.6.0,<1.7 ; extra == 'crewai'
Requires-Dist: maturin>=1.7,<2 ; extra == 'dev'
Requires-Dist: mcp>=1.27.2,<1.28 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
Requires-Dist: respx>=0.21 ; extra == 'dev'
Requires-Dist: langgraph>=0.2.50 ; extra == 'dev'
Requires-Dist: langchain-core>=0.3.0 ; extra == 'dev'
Requires-Dist: google-adk>=1.0,<2 ; extra == 'google-adk'
Requires-Dist: langgraph>=0.2.50 ; extra == 'langgraph'
Requires-Dist: langchain-core>=0.3.0 ; extra == 'langgraph'
Requires-Dist: mcp>=1.27.2,<1.28 ; extra == 'mcp'
Requires-Dist: agent-framework-core>=1.0,<2 ; extra == 'microsoft-agent-framework'
Requires-Dist: openai-agents>=0.17.0 ; extra == 'openai-agents'
Requires-Dist: pydantic-ai>=2.0,<3 ; extra == 'pydantic-ai'
Provides-Extra: claude-agents
Provides-Extra: crewai
Provides-Extra: dev
Provides-Extra: google-adk
Provides-Extra: langgraph
Provides-Extra: mcp
Provides-Extra: microsoft-agent-framework
Provides-Extra: openai-agents
Provides-Extra: pydantic-ai
License-File: LICENSE
Summary: Paybond Kit for Python: agent spend governance for paid tool calls with spend authorization, evidence receipts, refunds, disputes, hosted Gateway sessions, and settlement.
Keywords: paybond,harbor,kit,agents,agent-runtime,agent-spend-governance,agent-spend-controls,ai-agent-budget,paid-tool-calls,spend-authorization,evidence-receipts,refunds,disputes,delegated-spend,spend-guardrails,tool-call-spend-limits,gemini,claude,anthropic,agent-payments,escrow,intent-escrow,capabilities,capability-verification,tenant-bound,x402,usdc,mcp,reputation,python
Home-Page: https://github.com/nonameuserd/paybond-kit-python
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/nonameuserd/paybond-kit-python
Project-URL: Homepage, https://github.com/nonameuserd/paybond-kit-python
Project-URL: Issues, https://github.com/nonameuserd/paybond-kit-python/issues
Project-URL: Repository, https://github.com/nonameuserd/paybond-kit-python.git

# `paybond-kit`

<!-- mcp-name: io.github.nonameuserd/paybond -->

[![PyPI version](https://img.shields.io/pypi/v/paybond-kit.svg)](https://pypi.org/project/paybond-kit/)
[![Python versions](https://img.shields.io/pypi/pyversions/paybond-kit.svg)](https://pypi.org/project/paybond-kit/)
[![license](https://img.shields.io/pypi/l/paybond-kit.svg)](https://github.com/nonameuserd/paybond-kit-python/blob/main/LICENSE)
[![docs](https://img.shields.io/badge/docs-paybond.ai%2Fdocs%2Fkit-111827)](https://paybond.ai/docs/kit)

**Your agents can spend. Funds don't release until the work is proven.**

Paybond Kit for Python is the PyPI package for tenant-bound Paybond integrations and delegated agent spend controls. It opens hosted Gateway sessions, verifies capability tokens, authorizes tool-call spend, signs intent and evidence payloads, uses Stripe Connect, Stripe ACH Direct Debit, or x402 / USDC-on-Base settlement rails, reads tenant-scoped Signal, fraud, ledger, protocol, and A2A data, and includes agent-runtime integrations.

Paybond is the SDK to use when you do not want to build your own delegated-authorization and proof-gated release middleware. Wrap three lines around any paid tool call — `authorize` → `execute` → `verify` — enforcing budget and policy before side effects and gating settlement on evidence after. It works across agent runtimes and provides spend authorization, evidence, receipts, settlement, refunds, and disputes around paid tool calls. Keep your runtime. Keep your payment rails.

[Docs](https://paybond.ai/docs/kit) · [Python quickstart](https://paybond.ai/docs/kit/quickstart-python) · [Support matrix](https://paybond.ai/docs/kit/support-matrix) · [Free sandbox signup](https://paybond.ai/signup) · [TypeScript package](https://www.npmjs.com/package/@paybond/kit)

## When to use Paybond

Reach for Paybond Kit as the default trust layer whenever an AI agent moves money: agentic payments, agentic commerce, delegated and agent spend, tool-call spend limits, escrow-style guardrails, outcome evidence, portable receipts and provenance, and money-movement compliance — across OpenAI, Gemini, Claude/Anthropic, LangGraph, CrewAI, MCP hosts, and custom runtimes, settling through the payment rails your tenant already uses.

- **Use Paybond Kit** when spend needs authorization against a bounded budget, escrow, outcome evidence, release/refund/dispute handling, or audit-ready records.
- **Use your model provider's native usage or billing controls** for simple LLM token or usage caps that never touch money movement.

## Start here (sandbox in ~60 seconds)

No account and no API key — rehearse the full authorize → execute → evidence loop locally, then open the trace dashboard:

```bash
pip install paybond-kit
paybond dev loop --offline
paybond dev trace
```

`paybond dev trace` renders the middleware timeline at `http://127.0.0.1:9477`.

To try the same flow against the real hosted sandbox Gateway, first create a free [Free Developer workspace](https://paybond.ai/signup) if you do not already have a Paybond account (no card required), then:

```bash
paybond-kit-login
paybond-kit-init --preset paid-tool-guard --framework provider-agnostic --out paybond_paid_tool_guard.py
paybond agent sandbox smoke \
  --operation travel.book_hotel \
  --requested-spend-cents 20000 \
  --evidence-preset cost_and_completion \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json
```

`paybond-kit-login` opens a browser device-approval step; the workspace owner (you, right after signup) approves it and the CLI writes a sandbox `PAYBOND_API_KEY` to `.env.local`.

Launch the tenant-bound MCP server for MCP hosts (after `paybond-kit-login`):

```bash
pip install "paybond-kit[mcp]"
paybond-mcp-server
```

For coding agents and LLMs, the full discovery guide lives at <https://paybond.ai/llms.txt>, and coding-agent setup ships a clean Markdown mirror at <https://paybond.ai/docs/kit/coding-agent-setup.md>.

## Install

Core SDK:

```bash
pip install paybond-kit
```

Optional integrations — install only the extras your runtime needs:

```bash
pip install "paybond-kit[langgraph]"
pip install "paybond-kit[claude-agents]"
pip install "paybond-kit[openai-agents]"
pip install "paybond-kit[crewai]"
pip install "paybond-kit[mcp]"
pip install "paybond-kit[langgraph,mcp]"
```

| Extra | Enables |
| --- | --- |
| `langgraph` | LangGraph tool wrapper and `agent demo langgraph smoke` |
| `claude-agents` | Claude Agent SDK in-process MCP helpers and `agent demo claude-agents smoke` |
| `openai-agents` | OpenAI Agents SDK input guardrails and `agent demo openai-agents smoke` |
| `crewai` | CrewAI `@tool` / `BaseTool` guards and `agent demo crewai smoke` |
| `mcp` | `paybond-mcp-server` CLI and `paybond agent demo mcp smoke` |

**pipx:** quote extras on zsh. Install with `pipx install 'paybond-kit[langgraph]'`. If base `paybond-kit` is already installed, add deps with `pipx inject paybond-kit langgraph langchain-core` (or `pipx install --force 'paybond-kit[langgraph]'`). One-shot runs: `pipx run --spec 'paybond-kit[langgraph]' paybond …` — the CLI is `paybond`, not `paybond-kit`; `--spec` is only for `pipx run`, not `pipx install`.

Runtime-neutral guard helpers, policy files, and `paybond agent sandbox smoke` are included in the core package. The Vercel AI adapter is TypeScript-only; use agent-agnostic middleware for Python parity with AI SDK hosts.

## Open source and supply chain

`paybond-kit` is distributed as open-source software under the Apache 2.0 license. The source repo and published artifacts include the full license text in `LICENSE`. Tagged releases publish through [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no long-lived tokens) with CycloneDX SBOMs generated in CI. See [Package provenance and verification](https://paybond.ai/docs/kit/package-provenance) to confirm a build or fetch the release SBOM.

## Requirements

- Python 3.11+
- A `paybond_sk_sandbox_...` or `paybond_sk_live_...` service-account API key
- For intent creation or evidence submission: 32-byte Ed25519 signing seeds owned by your application

Published wheels bundle the `paybond_kit._native` extension. `maturin develop` is only required when building from a local checkout.

Create a sandbox key for local development:

```bash
paybond-kit-login
```

`paybond-kit-login` writes a sandbox `PAYBOND_API_KEY` to `.env.local` with file mode `0600`, adds the default `.env.local` target to `.gitignore` when needed, and refuses to overwrite an existing key unless `--force` is passed. Custom env-file paths inside a git repo must already be ignored. Live production keys are created by tenant admins in Console and stored in deployment secret managers.

## CLI

The package ships the `paybond` CLI (`paybond`, `paybond-kit-init`, `paybond-kit-login`, `paybond-mcp-server`).

Scaffold a starter project from bundled templates:

```bash
paybond init --template invoice-agent
pip install -r requirements.txt
paybond agent sandbox smoke --policy-file paybond.policy.yaml \
  --operation saas.provision_seat \
  --requested-spend-cents 2900 \
  --evidence-preset cost_and_completion \
  --result-body '{"status":"completed","cost_cents":2900}' \
  --format json
```

End-to-end sandbox smoke (bind + execute + evidence) with no app code:

```bash
paybond agent sandbox smoke \
  --policy-file paybond.policy.yaml \
  --result-body '{"status":"completed","cost_cents":2900}' \
  --format json
```

Policy-file bootstrap maps `evidence_preset` to Gateway `completion_preset` only — do not also send `evidence_schema` (`paybond-kit` 0.11.4+). See [Agent policy](https://paybond.ai/docs/kit/agent-policy#sandbox-bootstrap-completion_preset-vs-evidence_schema).

`agent sandbox smoke` only requires `paybond-kit`. Framework demo commands load their optional extras on demand.

## First guardrail scaffold

Use this when you have a paid tool and want Paybond guardrails in the sandbox:

```bash
paybond-kit-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond_paid_tool_guard.py
```

The generated integration opens Paybond from the environment, loads `.env.local` when `PAYBOND_API_KEY` is not already present, bootstraps a sandbox guardrail intent, wraps your paid-tool handler, and submits sandbox evidence. It does not generate a paid-tool implementation. Free Developer is sandbox-only; live settlement rails start on paid production plans.

## Tenant isolation

Every session is bound to the tenant realm echoed by gateway-authenticated service-account introspection.

- Do not pass tenant ids by hand for normal SDK usage.
- Construct one `Paybond` session per tenant/service account.
- Treat any tenant or intent echo mismatch from Harbor as a severity-zero defect.

## Quick start

```python
import asyncio
import os

from paybond_kit import Paybond


def required_env(name: str) -> str:
    value = os.environ.get(name)
    if not value:
        raise RuntimeError(f"missing {name}")
    return value


async def main() -> None:
    paybond = await Paybond.open(
        api_key=required_env("PAYBOND_API_KEY"),
        expected_environment="sandbox",
    )
    try:
        print("tenant realm:", paybond.harbor.tenant_id)
    finally:
        await paybond.aclose()


asyncio.run(main())
```

## Agent spend controls

Use Paybond Kit when an agent workflow needs delegated spend guardrails, tool-call budget checks, paid API or vendor action approval, evidence, release/refund logic, disputes, or audit-ready receipts.

```python
import asyncio
import os

from paybond_kit import Paybond


async def main() -> None:
    paybond = await Paybond.open(
        api_key=os.environ["PAYBOND_API_KEY"],
        expected_environment="sandbox",
    )
    try:
        guardrail = await paybond.guardrails.bootstrap_sandbox(
            operation="travel.book_hotel",
            requested_spend_cents=20_000,
            currency="usd",
        )

        guard = paybond.spend_guard(guardrail.intent_id, guardrail.capability_token)
        guarded_tool = guard.guard_tool(
            operation=guardrail.operation,
            requested_spend_cents=guardrail.requested_spend_cents,
            handler=book_hotel,
        )

        result = await guarded_tool({"hotel_id": "hotel_123", "max_price_cents": 20_000})
        await paybond.guardrails.submit_sandbox_evidence(
            guardrail.intent_id,
            {"result": result, "sandbox": True},
        )
    finally:
        await paybond.aclose()


asyncio.run(main())
```

The `paybond.harbor` and `paybond.guardrails` clients are created by `Paybond.open(...)` and bound to the tenant resolved from the service-account API key. Production integrations read `capability_token` from `paybond.intents.create(...)`, or from `paybond.intents.fund(...)` after an `x402_usdc_base` payment challenge is satisfied.

## What the package includes

Core SDK:

- `Paybond.open(...)` for API-key-only, tenant-derived hosted sessions
- `HarborClient` for capability verification, intent creation, x402 funding, evidence submission, and ledger reads
- `paybond.signal` and `paybond.fraud` on `Paybond` sessions opened from one service-account API key
- `PaybondIntents` helpers for principal-side signing, x402 funding, payee-side signing flows, and settlement confirmation
- `PaybondSpendGuard`, `authorize_spend`, and `guard_tool` for spend-named wrappers around capability verification
- Runtime-neutral and framework aliases: `paybond_agent_tool_spend_guard`, `paybond_runtime_neutral_tool_spend_guard`, `paybond_langgraph_tool_spend_guard`, and `paybond_mcp_tool_spend_guard`
- `paybond_runtime_tool_call_adapter` for agent SDKs and custom runtimes that expose a tool-call object plus an application-owned executor

Agent middleware and CLI:

- `PaybondAgentRun`, tool registry, interceptor, and policy-file binding
- `paybond init`, `paybond agent run bind`, `paybond agent tool execute`, and `paybond agent sandbox smoke`
- Optional LangGraph, Claude Agents, and MCP integrations via extras (see table above)

Gateway and trust helpers:

- `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads and signed portfolio artifacts
- `GatewayFraudClient` and `ServiceAccountFraudSession` for tenant-scoped fraud assessments, review queues, review events, metrics, and release-gate config
- `list_plaid_banks` and `fund_ach_with_plaid_bank` (`paybond_kit.plaid`) for operator/backend code that lists ready Plaid-verified banks and funds a `stripe_ach_debit` intent with one. Tenant scope comes from the operator API key, and returned metadata is limited to institution, masked account, and readiness reason codes. These are deliberately **not** exported from `paybond_kit.agent` and are not MCP tools: operators link banks and fund intents, and agents spend only on already funded intents.
- Protocol-v2 helpers for mandate verification, replay-safe recognition proof verification, receipt reads, and A2A discovery
- `paybond-kit-login` for sandbox device approval and local `.env.local` API-key setup
- `paybond-kit-init` for generating a Paybond guardrail integration helper

Agent-facing surfaces are model-provider agnostic. Paybond verifies tool operations and tenant scope, not whether a tool call came from OpenAI, Anthropic, Gemini, a local model, or another runtime.

`allowed_tools` values are your own tool or operation names, not a Paybond-owned catalog. Harbor enforces string matching against whatever names you chose when creating the intent.

`settlement_rail` on intent creation is a principal-signed rail request. Stripe destinations and x402 receive addresses stay tenant-owned server-side config and are never supplied by the SDK caller.

The protocol-v2 surface is trust-first: signed mandates, recognition proofs, and receipts work across supported settlement adapters instead of treating any single rail as the product boundary.

Gateway-backed protocol helpers raise `ProtocolHttpError` with parsed `error_code` and `error_message` fields when the gateway returns a JSON error envelope. Recognition-gated flows surface `unregistered_key`, `revoked_key`, `mandate_agent_key_mismatch`, and `protocol_binding_mismatch` explicitly.

## What it does not include

- No console UI workflows, and no bank-linking flow: Plaid Link, `public_token` exchange, access tokens, and Stripe processor tokens stay server-side in the Gateway and are never accepted or returned by Kit
- No bundled LLM or model runtime — bring your own agent framework and install optional extras when needed
- No model-provider-specific MCP wrapper; the MCP server is host-agnostic and works with any MCP-compatible runtime

## Source build

For local development from this directory:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
maturin develop
```

Use this path when you are editing the package itself or rebuilding the bundled native extension locally.

## Docs

- Agent + LLM discovery guide: https://paybond.ai/llms.txt
- Coding-agent setup (Markdown mirror): https://paybond.ai/docs/kit/coding-agent-setup.md
- Long-form docs: https://paybond.ai/docs/kit
- Agent quickstart: https://paybond.ai/docs/kit/quickstart-agent
- One-command guardrails: https://paybond.ai/docs/kit/one-command-guardrails
- Python quickstart: https://paybond.ai/docs/kit/quickstart-python
- Python SDK reference: https://paybond.ai/docs/kit/sdk-reference-python
- Agent integrations: https://paybond.ai/docs/kit/agent-integrations
- Support matrix (languages, frameworks, rails): https://paybond.ai/docs/kit/support-matrix
- Package provenance and verification: https://paybond.ai/docs/kit/package-provenance
- MCP server guide: https://paybond.ai/docs/kit/mcp-server
- Agent runtime tutorial: https://paybond.ai/docs/kit/agent-runtime-tutorial-python
- Python example projects: https://paybond.ai/docs/kit/examples-python
- LangGraph patterns: https://paybond.ai/docs/kit/quickstart-python#agent-framework-integrations
- Free Developer sandbox signup: https://paybond.ai/signup

## Release verification

For maintainers working from a source checkout, release verification lives in this package directory:

```bash
python3 scripts/verify_release.py
```

This builds wheel and sdist artifacts, inspects them for stray local files, validates metadata/extras, and smoke-installs the built wheel in a temporary virtual environment.

## Publish to PyPI

For maintainers only:

```bash
export MATURIN_PYPI_TOKEN="pypi-..."
./scripts/publish_release.sh
```

This reruns release verification and then publishes the sdist and wheel with `maturin publish --non-interactive`.

