@paybond/kit

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

Paybond Kit for TypeScript is the npm 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 · TypeScript quickstart · Support matrix · Free sandbox signup · Python package

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, Vercel AI SDK, LangGraph, 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:

npm install @paybond/kit
npx -p @paybond/kit paybond dev loop --offline
npx -p @paybond/kit 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 if you do not already have a Paybond account (no card required), then:

npx -p @paybond/kit paybond login
npx -p @paybond/kit paybond-init --preset paid-tool-guard --framework provider-agnostic --out paybond-paid-tool-guard.ts
npx -p @paybond/kit 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 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 login):

npx -y -p @paybond/kit 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

npm install @paybond/kit

@paybond/kit is an ESM-only package for Node.js runtimes. Use import from a Node ESM / NodeNext project or a compatible bundler.

Optional framework integrations

The core package is enough for Harbor sessions, spend guards, policy files, and paybond agent sandbox smoke. Install optional peers only when you import a framework subpath:

npm install ai @openai/agents @langchain/core @langchain/langgraph @anthropic-ai/claude-agent-sdk @google/adk @mastra/core agents

Thin npm wrappers (@paybond/vercel-ai, @paybond/langgraph, @paybond/openai-agents, @paybond/claude-agents, @paybond/google-adk, @paybond/mastra, @paybond/cloudflare-agents, @paybond/agent, @paybond/mcp) re-export the same subpaths for npm discoverability — install whichever matches your framework instead of the whole peer list above.

Open source and supply chain

@paybond/kit is distributed as open-source software under the Apache 2.0 license. The published npm package includes the full license text in LICENSE. Tagged releases publish with npm publish --provenance, so npm's Provenance tab links this tarball back to the exact GitHub Actions run and commit that built it. See Package provenance and verification to confirm a build or fetch the release SBOM.

Requirements

• Node.js 22+
• 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

Create a sandbox key for local development:

npx -p @paybond/kit paybond login

paybond 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-init, paybond-kit-login, paybond-mcp-server).

Scaffold a starter project from bundled templates:

npx -p @paybond/kit paybond init --template travel-agent
npm install
npm run smoke

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

npx -p @paybond/kit paybond agent sandbox smoke \
  --policy-file paybond.policy.yaml \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

With --policy-file, Kit sends completion_preset from the tool's evidence_preset and omits evidence_schema and template_id (Gateway rejects conflicting bootstrap fields). Requires @paybond/kit 0.11.11+.

agent sandbox smoke only requires @paybond/kit. Framework demo commands (agent demo vercel-ai smoke, etc.) load their optional peers on demand.

Offline local dev loop and trace dashboard:

npx -p @paybond/kit paybond dev loop --offline
npx -p @paybond/kit paybond dev trace

First guardrail scaffold

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

npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts

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

import { Paybond } from "@paybond/kit";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`missing ${name}`);
  }
  return value;
}

const paybond = await Paybond.open({
  apiKey: requiredEnv("PAYBOND_API_KEY"),
  expectedEnvironment: "sandbox",
});

try {
  console.log("tenant realm:", paybond.harbor.tenantId);
} finally {
  await paybond.aclose();
}

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.

import { Paybond } from "@paybond/kit";

const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
  expectedEnvironment: "sandbox",
});

const guardrail = await paybond.guardrails.bootstrapSandbox({
  operation: "travel.book_hotel",
  requestedSpendCents: 20_000,
  currency: "usd",
});

const guard = paybond.spendGuard(guardrail.intent_id, guardrail.capability_token);
const guardedTool = guard.guardTool(
  {
    operation: guardrail.operation,
    requestedSpendCents: guardrail.requested_spend_cents,
  },
  async (input) => bookHotel(input),
);