{
  "markdown": "# `@paybond/kit`\n\n<!-- mcp-name: io.github.nonameuserd/paybond -->\n\n[![npm version](https://img.shields.io/npm/v/@paybond/kit.svg)](https://www.npmjs.com/package/@paybond/kit)\n[![npm downloads](https://img.shields.io/npm/dm/@paybond/kit.svg)](https://www.npmjs.com/package/@paybond/kit)\n[![license](https://img.shields.io/npm/l/@paybond/kit.svg)](https://github.com/nonameuserd/paybond-kit/blob/main/LICENSE)\n[![docs](https://img.shields.io/badge/docs-paybond.ai%2Fdocs%2Fkit-111827)](https://paybond.ai/docs/kit)\n\n**Your agents can spend. Funds don't release until the work is proven.**\n\nPaybond 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.\n\nPaybond 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.\n\n[Docs](https://paybond.ai/docs/kit) · [TypeScript quickstart](https://paybond.ai/docs/kit/quickstart-typescript) · [Support matrix](https://paybond.ai/docs/kit/support-matrix) · [Free sandbox signup](https://paybond.ai/signup) · [Python package](https://pypi.org/project/paybond-kit/)\n\n## When to use Paybond\n\nReach 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.\n\n- **Use Paybond Kit** when spend needs authorization against a bounded budget, escrow, outcome evidence, release/refund/dispute handling, or audit-ready records.\n- **Use your model provider's native usage or billing controls** for simple LLM token or usage caps that never touch money movement.\n\n## Start here (sandbox in ~60 seconds)\n\nNo account and no API key — rehearse the full authorize → execute → evidence loop locally, then open the trace dashboard:\n\n```bash\nnpm install @paybond/kit\nnpx -p @paybond/kit paybond dev loop --offline\nnpx -p @paybond/kit paybond dev trace\n```\n\n`paybond dev trace` renders the middleware timeline at `http://127.0.0.1:9477`.\n\nTo 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:\n\n```bash\nnpx -p @paybond/kit paybond login\nnpx -p @paybond/kit paybond-init --preset paid-tool-guard --framework provider-agnostic --out paybond-paid-tool-guard.ts\nnpx -p @paybond/kit paybond agent sandbox smoke \\\n  --operation travel.book_hotel \\\n  --requested-spend-cents 20000 \\\n  --evidence-preset cost_and_completion \\\n  --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' \\\n  --format json\n```\n\n`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`.\n\nLaunch the tenant-bound MCP server for MCP hosts (after `paybond login`):\n\n```bash\nnpx -y -p @paybond/kit paybond-mcp-server\n```\n\nFor 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>.\n\n## Install\n\n```bash\nnpm install @paybond/kit\n```\n\n`@paybond/kit` is an ESM-only package for Node.js runtimes. Use `import` from a Node ESM / `NodeNext` project or a compatible bundler.\n\n### Optional framework integrations\n\nThe 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:\n\n| Subpath | Peer dependency |\n| --- | --- |\n| `@paybond/kit/vercel-ai` | `ai` |\n| `@paybond/kit/openai-agents` | `@openai/agents` |\n| `@paybond/kit/langgraph` | `@langchain/core`, `@langchain/langgraph` |\n| `@paybond/kit/claude-agents` | `@anthropic-ai/claude-agent-sdk` |\n| `@paybond/kit/google-adk` | `@google/adk` |\n| `@paybond/kit/mastra` | `@mastra/core` |\n| `@paybond/kit/cloudflare-agents` | `agents`, `ai` |\n| `@paybond/kit/mcp`, `@paybond/kit/agent`, `@paybond/kit/policy` | none — no extra peers required |\n\n```bash\nnpm install ai @openai/agents @langchain/core @langchain/langgraph @anthropic-ai/claude-agent-sdk @google/adk @mastra/core agents\n```\n\nThin 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.\n\n## Open source and supply chain\n\n`@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](https://paybond.ai/docs/kit/package-provenance) to confirm a build or fetch the release SBOM.\n\n## Requirements\n\n- Node.js 22+\n- A `paybond_sk_sandbox_...` or `paybond_sk_live_...` service-account API key\n- For intent creation or evidence submission: 32-byte Ed25519 signing seeds owned by your application\n\nCreate a sandbox key for local development:\n\n```bash\nnpx -p @paybond/kit paybond login\n```\n\n`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.\n\n## CLI\n\nThe package ships the `paybond` CLI (`paybond`, `paybond-init`, `paybond-kit-login`, `paybond-mcp-server`).\n\nScaffold a starter project from bundled templates:\n\n```bash\nnpx -p @paybond/kit paybond init --template travel-agent\nnpm install\nnpm run smoke\n```\n\nEnd-to-end sandbox smoke (bind + execute + evidence) with no app code:\n\n```bash\nnpx -p @paybond/kit paybond agent sandbox smoke \\\n  --policy-file paybond.policy.yaml \\\n  --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' \\\n  --format json\n```\n\nWith `--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+.\n\n`agent sandbox smoke` only requires `@paybond/kit`. Framework demo commands (`agent demo vercel-ai smoke`, etc.) load their optional peers on demand.\n\nOffline local dev loop and trace dashboard:\n\n```bash\nnpx -p @paybond/kit paybond dev loop --offline\nnpx -p @paybond/kit paybond dev trace\n```\n\n## First guardrail scaffold\n\nUse this when you have a paid tool and want Paybond guardrails in the sandbox:\n\n```bash\nnpx -p @paybond/kit paybond-init \\\n  --preset paid-tool-guard \\\n  --framework provider-agnostic \\\n  --out paybond-paid-tool-guard.ts\n```\n\nThe 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.\n\n## Tenant isolation\n\nEvery session is bound to the tenant realm echoed by gateway-authenticated service-account introspection.\n\n- Do not pass tenant ids by hand for normal SDK usage.\n- Construct one `Paybond` session per tenant/service account.\n- Treat any tenant or intent echo mismatch from Harbor as a severity-zero defect.\n\n## Quick start\n\n```ts\nimport { Paybond } from \"@paybond/kit\";\n\nfunction requiredEnv(name: string): string {\n  const value = process.env[name];\n  if (!value) {\n    throw new Error(`missing ${name}`);\n  }\n  return value;\n}\n\nconst paybond = await Paybond.open({\n  apiKey: requiredEnv(\"PAYBOND_API_KEY\"),\n  expectedEnvironment: \"sandbox\",\n});\n\ntry {\n  console.log(\"tenant realm:\", paybond.harbor.tenantId);\n} finally {\n  await paybond.aclose();\n}\n```\n\n## Agent spend controls\n\nUse 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.\n\n```ts\nimport { Paybond } from \"@paybond/kit\";\n\nconst paybond = await Paybond.open({\n  apiKey: process.env.PAYBOND_API_KEY!,\n  expectedEnvironment: \"sandbox\",\n});\n\nconst guardrail = await paybond.guardrails.bootstrapSandbox({\n  operation: \"travel.book_hotel\",\n  requestedSpendCents: 20_000,\n  currency: \"usd\",\n});\n\nconst guard = paybond.spendGuard(guardrail.intent_id, guardrail.capability_token);\nconst guardedTool = guard.guardTool(\n  {\n    operation: guardrail.operation,\n    requestedSpendCents: guardrail.requested_spend_cents,\n  },\n  async (input) => bookHotel(input),\n);\n\nconst result = await guardedTool({ hotelId: \"hotel_123\", maxPriceCents: 20_000 });\nawait paybond.guardrails.submitSandboxEvidence({\n  intentId: guardrail.intent_id,\n  payload: { result, sandbox: true },\n});\n```\n\nThe `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.\n\n## What the package includes\n\nCore SDK:\n\n- `Paybond.open(...)` for API-key-only, tenant-derived hosted sessions\n- `HarborClient` for capability verification, intent creation, x402 funding, evidence submission, and ledger reads\n- `paybond.signal` and `paybond.fraud` on `Paybond` sessions opened from one service-account API key\n- `PaybondIntents` helpers for principal-signed intent creation, x402 funding, payee-signed evidence submission, and settlement confirmation\n- `PaybondSpendGuard`, `authorizeSpend`, and `guardTool` for spend-named wrappers around capability verification\n- Runtime-neutral and framework aliases: `paybondAgentToolSpendGuard`, `paybondRuntimeNeutralToolSpendGuard`, `paybondLangGraphToolSpendGuard`, and `paybondMCPToolSpendGuard`\n- `paybondRuntimeToolCallAdapter` for agent SDKs and custom runtimes that expose a tool-call object plus an application-owned executor\n\nAgent middleware (`@paybond/kit/agent`) and framework subpaths (`vercel-ai`, `openai-agents`, `langgraph`, `claude-agents`, `mcp`, `policy`):\n\n- `PaybondAgentRun`, tool registry, interceptor, and policy-file binding\n- Framework adapters with optional peer dependencies (see table above)\n- `paybond init`, `paybond agent run bind`, `paybond agent tool execute`, and `paybond agent sandbox smoke`\n\nGateway and trust helpers:\n\n- `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads and signed portfolio artifacts\n- `GatewayFraudClient` and `ServiceAccountFraudSession` for tenant-scoped fraud assessments, review queues, review events, metrics, and release-gate config\n- Protocol-v2 helpers for mandate verification, replay-safe recognition proof verification, receipt reads, and A2A discovery\n- `paybond login` for sandbox device approval and local `.env.local` API-key setup\n- `paybond-mcp-server` for tenant-bound MCP tool exposure to any MCP-compatible host\n- `paybond-init` for generating a Paybond guardrail integration helper\n\nAgent-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.\n\n`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.\n\n`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.\n\nThe 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.\n\nGateway-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.\n\n## What it does not include\n\n- No operator-tier settlement or console workflows\n- No bundled LLM or model runtime — bring your own agent framework and install optional peers when needed\n- No model-provider-specific MCP wrapper; the MCP server is host-agnostic and works with any MCP-compatible runtime\n\n## Docs\n\n- Agent and LLM discovery guide: https://paybond.ai/llms.txt\n- Coding-agent setup (Markdown mirror): https://paybond.ai/docs/kit/coding-agent-setup.md\n- Long-form docs: https://paybond.ai/docs/kit\n- Agent quickstart: https://paybond.ai/docs/kit/quickstart-agent\n- One-command guardrails: https://paybond.ai/docs/kit/one-command-guardrails\n- TypeScript quickstart: https://paybond.ai/docs/kit/quickstart-typescript\n- TypeScript SDK reference: https://paybond.ai/docs/kit/sdk-reference-typescript\n- Support matrix (languages, frameworks, rails): https://paybond.ai/docs/kit/support-matrix\n- Package provenance and verification: https://paybond.ai/docs/kit/package-provenance\n- MCP server guide: https://paybond.ai/docs/kit/mcp-server\n- Agent runtime tutorial: https://paybond.ai/docs/kit/agent-runtime-tutorial\n- TypeScript example projects: https://paybond.ai/docs/kit/examples-typescript\n- Free Developer sandbox signup: https://paybond.ai/signup\n\n## Release verification\n\nFor maintainers working from a source checkout, release verification lives in this package directory:\n\n```bash\nnpm run verify:release\n```\n\nThis runs tests, performs a clean build, inspects the packed tarball for stray files, and compiles a temporary consumer app against the packed package.\n",
  "bytes": 15034,
  "sha": "78ff74f5796a8a6dc896353484759a8c8a83ba95f362cf3db1047aa20a02fc1d",
  "repo_slug": "nonameuserd/paybond-kit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nonameuserd_paybond_9f090e83/readme"
}