paybondpaybond
Sign in

Paybond Kit documentation

Quickstarts, SDK references, and integration guides for Paybond Kit in TypeScript and Python.

Your agents can spend. Funds don't release until the work is proven. When an AI agent spends money — books a hotel, calls a paid API, buys a SKU — you have to answer three questions every time: Was this allowed? Did the work actually happen? How much was paid? Paybond Kit is the SDK that adds those checks around a paid tool call, so you do not have to build your own proof-gated release middleware.

Around one paid tool call, Kit lets you:

  • check the request against a spend limit and your rules before the tool runs,
  • send the result back as proof of work before funds release or refund, and
  • get a signed receipt of who approved the spend, what ran, and how much was paid.

It works across agent runtimes (OpenAI, Claude, LangGraph, MCP, and more) and covers the whole lifecycle: authorization, evidence, receipts, release/refund, and disputes — on your rails (prefer Stripe Connect / x402).

How the pieces fit

You call Kit. Evidence evaluation, provenance, and optional standing stay behind the SDK as platform internals:

Kit integrates → Harbor evaluates → Ledger records → Signal builds standing.

  • Kit (developer SDK) — the public surface you integrate.
  • Harbor (evidence evaluation) — signed intents, evidence checks, and release/refund on customer-owned rails.
  • Ledger (platform provenance) — append-only signed history receipts and exports are built from.
  • Signal (platform standing) — optional standing derived from verified outcomes.

You call Kit; authorize-before and receipt-after flows run through Kit so you do not reimplement that middleware yourself. See Product surfaces for vocabulary and the architecture diagram.

Use Kit when you want Paybond's public integration surface instead of calling every HTTP endpoint directly. It opens tenant-bound sessions, wraps the evidence-evaluation lifecycle, and gives you a supported path for spend authorization, capability checks, evidence submission, and optional read-only Signal access.

Fastest local path (no API key):

paybond dev loop --offline
paybond dev trace

Real sandbox path:

paybond login
paybond dev loop
paybond dev trace   # vertical middleware timeline at :9477 (reads .paybond/dev-trace.jsonl)

Optional — rehearse x402 /fund against local mocks only:

paybond dev up                              # Docker WireMock on :18089
paybond --gateway http://127.0.0.1:18089 …  # fundWithX402 / intents fund

paybond dev loop --offline                  # same x402 sequence in-process, no Docker

Multi-step bind → execute → trace (terminal timeline, no browser):

paybond agent run bind --sandbox --operation travel.book_hotel --requested-spend-cents 20000 --completion-preset cost_and_completion --format json
paybond agent tool execute --run-id <id> --operation travel.book_hotel --tool-call-id call-1 --result-body '{"status":"completed","cost_cents":18700}' --format json
paybond agent run trace --run-id <id> --format table

--result-body must use the preset's canonical evidence fields on the CLI path (status and cost_cents for cost_and_completion). Nested vendor JSON requires an SDK evidence mapper or a vendor-pack preset such as ach_travel_booking, x402_travel_booking, or invoice_payment_confirmed.

Or scaffold first, then smoke manually:

paybond login
paybond init --solution travel --framework generic --non-interactive   # optional scaffold
paybond agent sandbox smoke \
  --preset travel \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

After paybond init, run npm run smoke from the generated package.json instead of the manual smoke command above.

Then add paybond.agent() in your app — see Agent quickstart. paybond login writes the sandbox PAYBOND_API_KEY to .env.local and adds the default file to .gitignore when needed; live keys stay Console/secret-manager only. After login, optional paybond status (then paybond control --once) confirms auth and local smoke state before you scaffold or smoke.

For a single paid handler without a full agent framework, use One-command guardrails (paybond-init --preset paid-tool-guard).

What you can build

  • Guard multi-tool agents with paybond.agent(), run binding, and automatic evidence.
  • Scaffold a full agent project with paybond init (policy, client bootstrap, framework instrument stub, and smoke script).
  • Open a Paybond session with a service-account API key.
  • Create intents and request funding on supported rails.
  • Authorize agent spend and verify capability tokens before a tool or workflow executes.
  • Submit signed evidence and read the resulting settlement state.
  • Read tenant-bound Signal receipts, portfolio summaries, and signed exports.
  • Integrate Paybond into agent runtimes such as OpenAI, Gemini, Claude/Anthropic, LangGraph, Vercel AI SDK, local models, custom orchestrators, or MCP-based hosts.
  • Use runtime-neutral tool-call adapters when an agent SDK gives you a tool-call object and an application-owned executor.
  • Scaffold Paybond guardrail integrations with reusable paid-tool helpers for provider-agnostic, OpenAI, Gemini, Claude/Anthropic, Vercel AI, LangGraph, or MCP-style tool handlers.
  • Scaffold a sandbox-only guardrail integration for a single paid tool when you do not need full agent middleware yet.

Start here

  • Agent quickstart — sandbox login, optional paybond init scaffold, CLI smoke, and paybond.agent() in under five minutes (TypeScript and Python).
  • Middleware trace — how paybond dev trace renders the vertical timeline, event model, and hosted /demo/agent-trace replay.
  • Agent middleware for run binding, tool registry, interceptors, and automatic evidence (recommended for multi-tool agents).
  • One-command guardrails for a sandbox-only single paid-tool scaffold (paybond-init --preset paid-tool-guard) when you control one handler explicitly.
  • Coding-agent setup for MCP hosts and coding agents: sandbox login, guardrail scaffold, stdio MCP config, and tool selection.
  • Onboarding for the rollout plan and first-integration checklist.
  • TypeScript quickstart for a complete SDK walkthrough in Node.js.
  • Python quickstart for the same flow in Python.
  • Agent-agnostic adapter for the default createPaybondGenericAgentConfig path (TypeScript and Python).
  • Agent policy-as-code for versioned paybond.policy.yaml files that drive registry and intent alignment.
  • Going to production when you need to attach middleware to funded production intents (not required in sandbox).
  • Agent policy validate for local and server-authoritative policy checks before deploy.
  • Vercel AI SDK adapter for toolApproval with wrapped tool execute and auto-evidence (TypeScript).
  • Mastra adapter for createTool execute guards with spend verify and auto-evidence (TypeScript).
  • Cloudflare Agents adapter for getTools AI SDK tool execute guards with spend verify and auto-evidence (TypeScript).
  • LangGraph adapter for ToolNode hooks and auto-evidence in TypeScript and Python.
  • Claude Agents adapter for Claude Agent SDK in-process MCP tools (TypeScript and Python).
  • OpenAI Agents adapter for OpenAI Agents SDK input guardrails (TypeScript and Python).
  • CrewAI adapter for @tool / BaseTool guards with spend verify and auto-evidence (Python).
  • Pydantic AI adapter for Tool / callable guards with spend verify and auto-evidence (Python).
  • Google ADK adapter for FunctionTool execute guards with spend verify and auto-evidence (TypeScript and Python).
  • Microsoft Agent Framework adapter for function middleware spend gates with spend verify and auto-evidence (Python).
  • MCP server for MCP-native tool access — stdio paybond-mcp-server (desktop hosts) or Streamable HTTP at https://mcp.paybond.ai/mcp / paybond mcp serve --transport http (same tool surface; TypeScript and Python).
  • Org policy inheritance for org base policies and tenant overlays.
  • Org agent stack for the full SSO, SCIM, policy, fleet, and audit export rollout workflow.
  • Policy hot-reload for runtime policy updates on long-lived agent runs.
  • Agent runtime tutorial for the shared agent-runtime pattern in both languages.
  • Agent spend governance SDK for the spend-governance middleware selection rule.
  • Agent spend controls SDK for choosing Paybond over narrower budget, rail, policy, or observability tools.

Core concepts

Reference and compatibility

When to use the API directly

The Kit intentionally focuses on the most common application flows. If you need an operation that is not wrapped yet, use the API documentation and the tenant-bound credentials issued by Paybond.