Next.js agent checkout with bounded spend

Shopping and checkout agents in Next.js typically combine the App Router, the Vercel AI SDK, and server-side secrets. Paybond belongs on the server — bind middleware per request, never expose capability tokens to the browser.

TypeScript only. This guide uses @paybond/kit/vercel-ai (TypeScript-only). For Python shopping agents, use Let agents buy groceries with the agent-agnostic path.

Adapter reference: /docs/kit/vercel-ai.

• Server-only Paybond

  Open Kit and instrument in Route Handlers — never expose capability tokens to the browser.

• Request-scoped bind

  Lazy context + AsyncLocalStorage resolve intentId per request for streamText.

• Vercel AI toolApproval

  Harbor authorize before checkout tools; client receives streamed text only.

• TypeScript only

  App Router + Vercel AI samples are TypeScript; Python shopping uses the agent-agnostic grocery guide.

Why Paybond (not just Next.js and the AI SDK)?

App Router and Vercel AI SDK tool approvals do not enforce a spend limit, a per-operation permission check (capability token), or a signed completion receipt tied to a spend agreement (intent).

How it works

3-minute quickstart

Smoke the vercel-ai checkout sandbox contract — no Next.js server required for this check:

paybond login
paybond agent demo vercel-ai smoke \
  --operation commerce.checkout \
  --requested-spend-cents 1000 \
  --evidence-preset cost_and_completion \
  --format table

paybond login
paybond agent demo vercel-ai smoke \
  --operation commerce.checkout \
  --requested-spend-cents 1000 \
  --evidence-preset cost_and_completion \
  --format table

Scaffold the shopping preset:

paybond init --solution shopping --max-spend-usd 100 --framework vercel-ai --non-interactive
paybond policy init --preset shopping --out paybond.policy.yaml

paybond init --solution shopping --max-spend-usd 100 --framework vercel-ai --non-interactive
paybond policy init --preset shopping --out paybond.policy.yaml

When the smoke succeeds you should see:

• ✓ Spend approved
• ✓ Checkout completed
• ✓ Evidence verified (cost_and_completion)

What success looks like

Wire middleware

// lib/paybond.ts
import { Paybond } from "@paybond/kit";
import { AsyncLocalStorage } from "node:async_hooks";

const paybond = await Paybond.open({ apiKey: process.env.PAYBOND_API_KEY! });
const requestStore = new AsyncLocalStorage<{ runtime: Awaited<ReturnType<typeof instrumented.bind>> }>();

const instrumented = await paybond.instrument({
  policy: "./paybond.policy.yaml",
  framework: "vercel-ai",
  tools: {
    checkout: checkoutToolDef,
    searchProducts: searchProductsToolDef,
  },
  context: () => requestStore.getStore()!.runtime,
});

export { paybond, instrumented, requestStore };

Route handler

// app/api/agent/route.ts
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { instrumented, requestStore } from "@/lib/paybond";

export async function POST(req: Request) {
  const { prompt, intentId, capabilityToken } = await req.json();

  const runtime = await instrumented.bind({ intentId, capabilityToken });
  const { agentTools: tools, toolApproval } = runtime;

  return requestStore.run({ runtime }, async () => {
    const result = streamText({
      model: openai("gpt-4.1"),
      tools,
      toolApproval,
      prompt,
    });
    return result.toDataStreamResponse();
  });
}

Sandbox rehearsal: use paybond.agent({ policy: "shopping", framework: "vercel-ai", tools }) to skip manual bind during local dev.

Shopping preset defaults

See Let agents buy groceries for the full multi-tool shopping walkthrough.

Production checklist

Works with

Ready to test?

Related guides

• Vercel AI SDK spend controls — toolApproval primitives
• Let agents buy groceries — shopping preset
• Express and Fastify agent routes — non-Next.js HTTP servers

Developer reference: /docs/kit/vercel-ai.