# `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 AI agent shouldn't accidentally spend $20,000.**

An unsupervised agent that can book travel, call paid APIs, or buy compute can also loop through “approved” tool calls until the budget is gone — each charge succeeds, and nothing proves the work was delivered. Per-transaction caps alone do not stop that.

**`paybond-kit`** is the Python SDK for delegated agent spend controls: authorize against a bounded budget and policy *before* a paid tool runs, then release or refund only after signed completion evidence. Wrap three lines around any paid tool call — `authorize` → `execute` → `verify`. Keep your runtime. Keep your payment rails (prefer Stripe Connect / x402; Stripe ACH Direct Debit and USDC-on-Base are also available). You get spend authorization, evidence-gated settlement, refunds, disputes, and a portable signed receipt — without building your own proof-gated release middleware.

Under the hood, Kit opens hosted Gateway sessions, verifies capability tokens, signs intent and evidence payloads, and can read tenant-scoped Signal, fraud, ledger, protocol, and A2A data, with adapters for common agent runtimes.

[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 whenever an AI agent can move money and you need spend that stays inside a budget — not just token metering: agentic payments and commerce, tool-call spend limits, outcome evidence before release, and audit-ready records — 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, proof-gated release/refund/dispute handling, or audit-ready receipts.
- **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`.