paybondpaybond
Sign in

Mastra adapter

Paybond adapter for Mastra agents — wrap createTool execute handlers with spend verify and auto-evidence.

Paybond integrates with Mastra at the createTool({ execute }) boundary — spend verify runs before side-effecting tools execute, then auto-evidence fires after success. Model inference stays on your Mastra agent; Paybond guards paid and side-effecting tool calls only.

TypeScript only. Python Kit does not ship a Mastra adapter — use agent-agnostic middleware or MCP for Python hosts.

Install

Install

npm install @paybond/mastra @mastra/core

Import from @paybond/mastra

import { createPaybondMastraConfig } from "@paybond/mastra";
  • Equivalent subpath on the core package: `@paybond/kit/mastra` — use `@paybond/kit` when you need multiple adapters in one app.
  • TypeScript only. Python Kit does not ship a Mastra adapter — use agent-agnostic middleware or MCP.
  • Optional peer: @mastra/core >= 1.0.0 (tested with v1.x).
  • Smoke: `paybond agent demo mastra smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json`.

One-liner (sandbox): paybond.instrument({ policy, framework: "mastra", tools, sandbox: true }) or paybond.agent({ policy, framework: "mastra", tools }) returns guarded Mastra tools. Production: omit sandbox and call instrumented.bind() per session.

import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { Paybond } from "@paybond/kit";

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

const { tools } = await paybond.instrument({
  policy: "./paybond.policy.yaml", // or preset id "travel"
  framework: "mastra",
  tools: [
    createTool({
      id: "travel.book_hotel",
      description: "Book a hotel room",
      inputSchema: z.object({
        city: z.string(),
        estimatedPriceCents: z.number().int().nonnegative(),
      }),
      execute: async (args) => bookHotel(args),
    }),
  ],
});

// Register `tools` with your Mastra agent.

Already bound a run? Use createPaybondMastraConfig(run, tools) from @paybond/kit/mastra or @paybond/mastra.

See Agent middleware for run binding, registry rules, and tenant isolation.

Advanced / manual wiring

When you need step-by-step control over registry and bind:

  1. Bind a PaybondAgentRun with a tool registry (sandbox bootstrap or production attach).
  2. Register side-effecting tools on the registry — tool id must match registry keys.
  3. Wrap Mastra tools with createPaybondMastraConfig(run, tools) before registering on your agent.
import { createPaybondMastraConfig } from "@paybond/mastra";

const { tools: guardedTools } = createPaybondMastraConfig(run, mastraTools);

Paybond wraps execute only on side-effecting registry tools. Schema, id, and description pass through unchanged.

Scaffold and smoke

The smoke command exercises authorize → execute → auto-evidence without a Mastra agent runtime or LLM.

paybond login
paybond agent demo mastra smoke \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --format json

Vertical template: clone or scaffold the travel booking starter:

paybond init --template mastra-travel-agent --framework mastra
# or: git clone https://github.com/nonameuserd/paybond-mastra-travel-agent.git

Optional peer: @mastra/core >= 1.0.0 — required for the native adapter and smoke demo.

npm install @paybond/mastra @mastra/core
paybond init agent-middleware --framework mastra --out paybond-mastra.ts

Selection rule

Use Paybond for paid tools, delegated spend, receipts, and spend authorization. Use provider-native limits only for LLM token caps.