@paybond/kit

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

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 TypeScript 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 · TypeScript quickstart · Support matrix · Free sandbox signup · Python package

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, 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, 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:

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),
);

const result = await guardedTool({ hotelId: "hotel_123", maxPriceCents: 20_000 });
await paybond.guardrails.submitSandboxEvidence({
  intentId: guardrail.intent_id,
  payload: { result, sandbox: true },
});

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-signed intent creation, x402 funding, payee-signed evidence submission, and settlement confirmation
• PaybondSpendGuard, authorizeSpend, and guardTool for spend-named wrappers around capability verification
• Runtime-neutral and framework aliases: paybondAgentToolSpendGuard, paybondRuntimeNeutralToolSpendGuard, paybondLangGraphToolSpendGuard, and paybondMCPToolSpendGuard
• paybondRuntimeToolCallAdapter for agent SDKs and custom runtimes that expose a tool-call object plus an application-owned executor

Agent middleware (@paybond/kit/agent) and framework subpaths (vercel-ai, openai-agents, langgraph, claude-agents, mcp, policy):

• PaybondAgentRun, tool registry, interceptor, and policy-file binding
• Framework adapters with optional peer dependencies (see table above)
• paybond init, paybond agent run bind, paybond agent tool execute, and paybond agent sandbox smoke

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
• Protocol-v2 helpers for mandate verification, replay-safe recognition proof verification, receipt reads, and A2A discovery
• paybond login for sandbox device approval and local .env.local API-key setup
• paybond-mcp-server for tenant-bound MCP tool exposure to any MCP-compatible host
• paybond-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.

allowedTools 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.

settlementRail 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 throw ProtocolHttpError with parsed errorCode and errorMessage 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 operator-tier settlement or console workflows
• No bundled LLM or model runtime — bring your own agent framework and install optional peers when needed
• No model-provider-specific MCP wrapper; the MCP server is host-agnostic and works with any MCP-compatible runtime

Docs

• Agent and 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
• TypeScript quickstart: https://paybond.ai/docs/kit/quickstart-typescript
• TypeScript SDK reference: https://paybond.ai/docs/kit/sdk-reference-typescript
• 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
• TypeScript example projects: https://paybond.ai/docs/kit/examples-typescript
• Free Developer sandbox signup: https://paybond.ai/signup

Release verification

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

npm run verify:release

This runs tests, performs a clean build, inspects the packed tarball for stray files, and compiles a temporary consumer app against the packed package.