paybondpaybond
Sign in

One-command guardrails

Add Paybond's sandbox-only paid-tool guardrail path with one scaffold command before wiring production settlement.

Start here when the goal is: "I have a paid tool. Add Paybond guardrails in one command."

For coding agents choosing a setup path, see Coding-agent setup.

The first Paybond integration path is sandbox-only. It uses a Free Developer workspace, derives tenant scope from the sandbox service-account API key, bootstraps a sandbox guardrail intent, checks the paid-tool operation before work runs, submits simulator evidence, and returns a sandbox lifecycle result. It does not touch live settlement rails.

TypeScript

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

The scaffold writes reusable helpers around:

  • paybond.guardrails.bootstrapSandbox(...)
  • paybond.spendGuard(intentId, capabilityToken)
  • paybond.guardrails.submitSandboxEvidence(...)

Python

paybond-kit-login
paybond-kit-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond_paid_tool_guard.py

The scaffold writes reusable helpers around:

  • paybond.guardrails.bootstrap_sandbox(...)
  • paybond.spend_guard(intent_id, capability_token)
  • paybond.guardrails.submit_sandbox_evidence(...)

What the generated integration provides

The generated integration:

  1. Opens a tenant-bound Paybond session from PAYBOND_API_KEY.
  2. Calls the sandbox guardrail bootstrap route.
  3. Wraps your application-owned paid-tool handler with the returned intent_id and capability_token.
  4. Authorizes the operation and requested sandbox spend before the handler runs.
  5. Submits sandbox evidence after your handler returns.

The scaffold does not generate a paid-tool implementation. Keep the helper functions and pass your real tool handler, or an application-owned temporary test handler, to wrapPaidTool(...) / wrap_paid_tool(...).

The response includes tenant_id, intent_id, capability_token, operation, requested_spend_cents, and sandbox_lifecycle_status.

Production boundary

Free Developer is for sandbox integration only. When the sandbox guardrail path works and the workflow needs live settlement rails, move the tenant to Starter or higher and use the production Harbor create, fund, capability-check, evidence, and settlement flows documented in the TypeScript and Python quickstarts.

Team and Business overage remains on the existing intent and settled-volume meters where enabled. Paybond does not add a separate tool-call billing meter for this milestone.

Wire your tool

After paybond login or paybond-kit-login writes PAYBOND_API_KEY to .env.local, import the scaffold output from your application and call the helpers around your own paid tool. The generated helper loads .env.local when PAYBOND_API_KEY is not already in the process environment, which covers agent hosts that do not automatically read project env files.

import {
  bootstrapSandboxGuardrailIntent,
  openPaybondFromEnv,
  submitSandboxEvidence,
  wrapPaidTool,
} from "./paybond-paid-tool-guard.ts";

const paybond = await openPaybondFromEnv();
const guardrail = await bootstrapSandboxGuardrailIntent(paybond);
const guardedTool = wrapPaidTool(paybond, guardrail, yourPaidToolHandler);
const result = await guardedTool(yourToolInput);
await submitSandboxEvidence(paybond, guardrail, { result });

The Python helper follows the same shape: open Paybond, bootstrap the sandbox guardrail intent, pass your handler to wrap_paid_tool(...), then submit evidence from the returned result.