TypeScript quickstart

For a first paid-tool guardrail integration, start with the sandbox scaffold:

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

This Free Developer path is sandbox-only. It bootstraps a sandbox guardrail intent, wraps your paid-tool handler, submits simulator evidence, and does not generate a paid-tool implementation. See One-command guardrails for the focused walkthrough.

This quickstart shows the standard Paybond application flow in TypeScript:

1. Open an authenticated session against the Gateway with a service-account API key.
2. Create a principal-signed intent.
3. Read the funded intent's capability_token, or fund an x402 intent through /fund.
4. Verify that capability before tool work.
5. Submit signed evidence so Harbor can evaluate the predicate and transition the intent.

Every call below is tenant-scoped. The tenant comes from the Gateway exchange and is bound to the returned client, so you never pass a tenant ID by hand.

allowedTools should contain your application's own operation names. Paybond does not define that catalog; Harbor simply checks that the later authorizeSpend({ operation }) or verifyCapability({ operation }) call matches one of the names attached to the intent.

For the full API surface, see the TypeScript SDK reference.

Prerequisites

• Node.js 22+ (global fetch, crypto.randomUUID).
• A paybond_sk_sandbox_… or paybond_sk_live_… service-account API key issued for your tenant realm. For local sandbox work, run npx -p @paybond/kit paybond login; live production keys are created in Console by tenant admins and stored in your deployment secret manager.
• For the principal-signed intent create flow: a 32-byte Ed25519 seed for the principal and a 32-byte seed for the payee bound to the intent. The Kit validates seed length in paybond.intents.create and paybond.intents.submitEvidence.

Install

Install the public package:

npm install @paybond/kit

For a fuller runnable application, see the TypeScript example projects.

Sandbox login

npx -p @paybond/kit paybond login

The login CLI starts a sandbox device approval flow, writes 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. It prints the masked key identity and target sandbox tenant only; it never prints the raw key after writing.

Authenticated session

Paybond.open resolves the tenant realm from the hosted Gateway and returns tenant-bound Gateway, Harbor, Signal, fraud, A2A, and protocol clients. The examples below assume a sandbox key; set expectedEnvironment to "live" when using a paybond_sk_live_… key. The paybond.harbor property is created by Paybond.open(...); use paybond.spendGuard(...) for normal tool guards and paybond.harbor directly only for lower-level Harbor calls.

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

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

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

Key properties of the session:

• Tenant is derived, not supplied. The tenant realm is whatever the Gateway echoes. Do not read the tenant from request bodies or environment variables at call time.
• Gateway is the public surface. Harbor operations go through Gateway's tenant-scoped /harbor and /verify routes.
• Sessions are single-tenant. Construct one Paybond instance per (tenant, service account). Never share across tenants or reuse across concurrent runs bound to different intents.
• Release resources. Always finish with await paybond.aclose() when the session is done. Paybond.open throws GatewayAuthError on any gateway or token failure.

Capability token source

Normal integrations do not supply capability tokens through environment variables. The token comes from the intent lifecycle:

• paybond.intents.create(...) returns capability_token when the selected rail funds the intent immediately.
• paybond.intents.fund(...) returns capabilityToken after an x402_usdc_base funding challenge is satisfied.
• If you do not pass intentId to create, read the generated id from created.intent_id.

Notes:

• paybond.spendGuard(...).authorizeSpend(...) and lower-level verifyCapability calls go through Gateway POST /verify. A 200 response with allow: false is a business denial, not an HTTP transport error.
• paybond.intents.submitEvidence signs the payee evidence binding and posts it to Gateway POST /harbor/intents/{id}/evidence. Reuse the same idempotencyKey when retrying the same submission.
• The client validates tenant and intent echoes on protected reads and writes so mismatched responses fail closed.
• Keep payeeSigningSeed in a secret manager. The value must be exactly 32 bytes and must correspond to the payee key bound on the intent.

Recognition proofs

Every Gateway-backed Harbor mutation in these snippets takes a recognitionProof. Think of it as a short-lived signature that says: "this tenant-registered agent key is authorizing this exact Gateway request right now."

Paybond does not create or hand this proof to your app, and Kit does not generate it automatically. The proof is created by your trusted backend, KMS-backed signer, wallet service, or agent runner:

1. A tenant admin registers the agent runtime's Ed25519 public key in Paybond's trusted agent key registry and assigns it a stable key_id.
2. Your trusted component keeps the matching Ed25519 private key. Do not expose that key to a browser, model prompt, or untrusted tool.
3. Immediately before a protected mutation, that component signs a fresh AgentRecognitionProofV1 for the exact request.
4. Kit base64url-encodes the finished proof object and sends it as x-paybond-agent-recognition-proof.
5. Gateway verifies the signature against the registered public key, checks tenant/purpose/request binding, and rejects replayed nonces.

A typical app keeps this behind an internal helper or endpoint:

type IssueAgentRecognitionProofV1 = (input: {
  purpose: "harbor.intent.create" | "harbor.intent.fund" | "harbor.intent.evidence.submit";
  method: "POST";
  path: string;
  body: Record<string, unknown>;
}) => Promise<AgentRecognitionProofV1>;

Generate a fresh proof after the request body is fixed:

Because the proof covers the body digest, the proof issuer must run where it can see or reproduce the final request body. If you prebuild Harbor bodies outside the high-level helpers, send them through the lower-level Gateway Harbor methods such as paybond.harbor.createIntent(...) and paybond.harbor.submitEvidence(...).

Each proof should include schema_version: 1, kind: "paybond.agent_recognition_proof_v1", the tenant-registered key_id, signature_algorithm: "ed25519-sha256-json-v1", verifier_context.tenant_id: paybond.harbor.tenantId, verifier_context.verifier_id: "paybond-gateway", a request envelope, a unique nonce, a short issued_at / expires_at window of 10 minutes or less, and the Ed25519 digest/signature fields.

Only PAYBOND_API_KEY is Paybond-issued in these examples. The APP_* environment variables below are local sandbox/live quick-start placeholders for values owned by your application, such as agent DIDs, signing seeds, rail choices, wallet signatures, and proof JSON returned by your signer. They are not static production config. Production code should call your proof issuer for each create, fund, fund retry, and submitEvidence request.

Principal-signed intent create

paybond.intents.create builds a principal-signed intent body and submits it through Gateway POST /harbor/intents. intentId can default to crypto.randomUUID() when omitted, but this quickstart passes it explicitly so the recognition proof can bind to a stable request. The example below creates the intent, reads its returned capability token, verifies the tool operation, and submits evidence.

import { Buffer } from "node:buffer";
import { Paybond } from "@paybond/kit";

function seed32FromHex(hex: string): Uint8Array {
  const buf = Buffer.from(hex.replace(/^0x/i, ""), "hex");
  if (buf.length !== 32) {
    throw new Error("seed must be 32 bytes (64 hex characters)");
  }
  return new Uint8Array(buf);
}

const principalSeed = seed32FromHex(process.env.APP_PRINCIPAL_SEED_HEX!);
const payeeSeed = seed32FromHex(process.env.APP_PAYEE_SEED_HEX!);

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

try {
  const intentId = crypto.randomUUID();
  const createRecognitionProof = JSON.parse(process.env.APP_INTENT_CREATE_RECOGNITION_PROOF_JSON!);
  const created = await paybond.intents.create({
    principalDid: "did:web:example.com#principal",
    principalSigningSeed: principalSeed,
    recognitionProof: createRecognitionProof,
    payeeDid: "did:web:example.com#booker-agent",
    budget: { currency: "usd", max_spend_usd: 200 },
    predicate: { version: 1, root: { op: "true" } },
    currency: "usd",
    amountCents: 20_000,
    evidenceSchema: { type: "object" },
    deadlineRfc3339: "2030-12-31T23:59:59Z",
    allowedTools: ["travel.planner.plan", "travel.booker.purchase"],
    settlementRail: "stripe_connect",
    intentId,
    idempotencyKey: `intent:${intentId}`,
  });

  if (String(created.intent_id) !== intentId) {
    throw new Error(`intent mismatch: requested=${intentId} gateway=${String(created.intent_id ?? "")}`);
  }

  const capabilityToken = String(created.capability_token ?? "");
  if (!capabilityToken) {
    throw new Error("intent created without capability_token; fund the intent before verifying tools");
  }

  const guard = paybond.spendGuard(intentId, capabilityToken);
  const verified = await guard.authorizeSpend({
    operation: "travel.booker.purchase",
    requestedSpendCents: 18_700,
  });
  if (!verified.allow) {
    throw new Error(`verify denied: ${verified.code ?? "deny"} ${verified.message ?? ""}`);
  }

  // Only run the real action after Paybond authorizes the agent to do it.

  const submittedAtRfc3339 = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
  const evidenceRecognitionProof = JSON.parse(process.env.APP_EVIDENCE_RECOGNITION_PROOF_JSON!);
  await paybond.intents.submitEvidence({
    intentId,
    payeeDid: "did:web:example.com#booker-agent",
    payeeSigningSeed: payeeSeed,
    recognitionProof: evidenceRecognitionProof,
    payload: { flight_booked: true, price: 187, confirmation: "PNR-4GH271" },
    artifactsBlake3Hex: [],
    submittedAtRfc3339,
    idempotencyKey: `evidence:${intentId}`,
  });
  console.log("created intent", intentId);
} finally {
  await paybond.aclose();
}

Choose intentId, submittedAtRfc3339, and idempotency keys before issuing request-bound recognition proofs so your signer can bind to the same request the SDK will send.

Managed-policy intent creation is not wrapped by this helper. If you need registry-bound signing, use paybond.harbor.createIntent with a pre-built body, request-bound recognition proof, and the Harbor policy registry.

allowedTools is your namespace, not Paybond's. For example, if your runtime later verifies operation: "travel.booker.purchase", that exact string must appear in the intent allow-list.

settlementRail is required and principal-signed. It requests one allowed rail such as stripe_connect, stripe_ach_debit, or x402_usdc_base; you are not supplying a Stripe destination or x402 receive address. Harbor resolves the destination from the tenant's canonical settlement config and snapshots it onto the intent.

Intent pricing remains USD-denominated even on the stablecoin rail: keep budget.currency and currency as "usd" with cent-based amounts, while x402_usdc_base tells Harbor to settle that value in USDC on Base.

Stablecoin funding via /fund

For intents created on the x402_usdc_base rail, Harbor returns a funding object with the payment-session metadata and the tenant-scoped harbor_fund_endpoint. The Kit wraps that flow with paybond.intents.fund.

The snippet below uses two app-owned helpers: issueAgentRecognitionProofV1(...) creates a fresh request-bound proof, and x402Wallet.signPayment(...) signs the x402 challenge returned by Harbor.

const fundRecognitionProof = await issueAgentRecognitionProofV1({
  purpose: "harbor.intent.fund",
  method: "POST",
  path: `/harbor/intents/${intentId}/fund`,
  body: {},
});
const first = await paybond.intents.fund({ intentId, recognitionProof: fundRecognitionProof });
if (first.statusCode === 402) {
  const paymentRequired = first.paymentRequired;
  if (!paymentRequired) {
    throw new Error("missing PAYMENT-REQUIRED challenge");
  }

  const paymentSignature = await x402Wallet.signPayment(paymentRequired);
  const retryRecognitionProof = await issueAgentRecognitionProofV1({
    purpose: "harbor.intent.fund",
    method: "POST",
    path: `/harbor/intents/${intentId}/fund`,
    body: {},
  });

  const funded = await paybond.intents.fund({
    intentId,
    recognitionProof: retryRecognitionProof,
    paymentSignature,
  });
  if (!funded.capabilityToken) {
    throw new Error("funding is pending; poll /fund with a fresh recognition proof before guarding tools");
  }
  console.log(funded.statusCode, funded.funded, funded.capabilityToken);
} else if (first.capabilityToken) {
  console.log(first.statusCode, first.funded, first.capabilityToken);
} else {
  throw new Error("intent is not funded yet; poll /fund with a fresh recognition proof before guarding tools");
}

Notes:

• issueAgentRecognitionProofV1(...) is your trusted backend or agent-runner signer, not a Kit helper. Local sandbox/live quick-start scripts may load APP_FUND_RECOGNITION_PROOF_JSON and APP_FUND_RETRY_RECOGNITION_PROOF_JSON from the environment, but production code should issue a fresh AgentRecognitionProofV1 for each /fund call.
• Generate the AgentRecognitionProofV1 with purpose: "harbor.intent.fund", verifier_context.tenant_id: paybond.harbor.tenantId, verifier_context.verifier_id: "paybond-gateway", and a request_envelope for POST /harbor/intents/{intentId}/fund whose body digest is the SHA-256 of the exact JSON body Kit sends ({} for this helper).
• Use a unique nonce, short issued_at/expires_at window, and the Ed25519 private key for a tenant-registered agent key_id; the signed proof includes message_digest_sha256_hex, signing_public_key_ed25519_hex, and ed25519_signature_hex.
• The retry needs its own recognition proof because proof nonces are single-use. paymentSignature is separate: it comes from your x402 wallet or facilitator after signing paymentRequired, and Kit sends it as the payment-signature header. If a local quick-start script uses APP_X402_PAYMENT_SIGNATURE, treat it as a stand-in for that signer output.
• paybond.intents.fund calls Gateway POST /harbor/intents/{id}/fund.
• 402 is a normal funding challenge, not an exception. The helper returns paymentRequired so your integration can call an x402-capable signer.
• 202 means authorization is pending; poll /fund with a fresh recognition proof before guarding tools. 200 means Harbor transitioned the intent to funded.

Advanced troubleshooting

Only use direct token verification when support asks you to inspect an existing funded intent. Keep this out of production app configuration; normal integrations should read the capability token from create or fund.

export PAYBOND_INTENT_ID="00000000-0000-0000-0000-000000000000"
export PAYBOND_CAPABILITY="paybond_cap_..."

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

try {
  const verified = await paybond.harbor.verifyCapability({
    intentId: process.env.PAYBOND_INTENT_ID!,
    token: process.env.PAYBOND_CAPABILITY!,
    operation: "travel.booker.purchase",
    requestedSpendCents: 18_700,
  });
  console.log(verified.allow, verified.code, verified.message);
} finally {
  await paybond.aclose();
}

Settlement confirmation

Settlement confirmation is an operator-tier action and is not wrapped by paybond.intents. Prefer the Operator Console for human-reviewed settlement; for protocol-driven automation, use paybond.protocol.confirmHarborSettlement({ intentId, body: {}, recognitionProof }). The helper confirms the settlement action implied by the stored evidence evaluation. See the Harbor API reference.

Error handling

See the Error handling guide for retry/backoff guidance and logging hygiene.

Further reading

• TypeScript SDK reference — full surface, including Paybond.open, paybond.intents.{create, fund, submitEvidence}, paybond.harbor.verifyCapability, paybond.aclose, and typed error classes.
• Authentication & tenant binding.
• Evidence & artifacts and Capabilities.
• Harbor API — the HTTP contract behind the SDK.
• TypeScript example projects.