ZBD x Vercel Agent Template

A Next.js starter for building AI agents that can pay and get paid over Lightning, deployed on Vercel.

---

What's Included

• Buy-side payments: agentFetch with zbdPayL402Invoice for fetching L402-protected APIs and paying automatically
• Sell-side payments: withPaymentRequired middleware for putting your own API endpoints behind a Lightning paywall
• AI SDK integration: Streaming chat endpoint with optional paid context fetched via L402
• Balance endpoint: Check your ZBD wallet balance at any time
• Token caching: VercelKVTokenCache for persisting L402 tokens across serverless invocations

---

Prerequisites

• Node.js >= 22
• A Vercel account
• A ZBD API key — get one at developer.zbdpay.com
• An OpenAI API key (optional, only needed for the chat demo)

---

Setup

1. Clone and install

   git clone https://github.com/zbdpay/vercel-template.git
   cd vercel-template
   npm install

2. Initialize your ZBD wallet

   npx @zbdpay/agent-wallet init --key YOUR_ZBD_API_KEY

   This creates a Lightning address for your agent and prints it out. Save it for the next step.

3. Add Vercel KV

   vercel kv add

   Or create a KV store from the Vercel dashboard and link it to your project. This is used to cache L402 tokens between requests.

4. Configure environment variables

   cp .env.example .env.local

   Then open .env.local and fill in:

   Variable	Description
   ZBD_API_KEY	Your ZBD API key
   ZBD_LIGHTNING_ADDRESS	The Lightning address from step 2
   KV_REST_API_URL	From Vercel KV dashboard
   KV_REST_API_TOKEN	From Vercel KV dashboard
   OPENAI_API_KEY	Optional, for the chat endpoint

5. Run the dev server

   npm run dev

6. Deploy

   vercel deploy

---

Test It

With the dev server running on http://localhost:3000:

# Check your wallet balance
curl http://localhost:3000/api/balance

# Buy-side: fetch a paid L402 API (agent pays automatically)
curl -X POST http://localhost:3000/api/agent \
  -H "Content-Type: application/json" \
  -d '{"url": "https://some-l402-api.example.com/data"}'

# Sell-side: hit the premium endpoint (returns 402 Payment Required)
curl -v http://localhost:3000/api/premium

# Chat with AI (streaming)
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

---

File Structure

vercel-template/
├── app/
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Interactive demo UI
│   └── api/
│       ├── agent/route.ts   # Buy-side: fetch paid APIs via L402
│       ├── balance/route.ts # Wallet balance check
│       ├── chat/route.ts    # AI SDK streaming + optional paid context
│       └── premium/route.ts # Sell-side: L402 paywall (100 sats)
├── lib/
│   ├── kv-token-cache.ts    # VercelKV-backed TokenCache implementation
│   └── zbd.ts               # Configured agentFetch helper
├── .env.example
├── next.config.ts
├── package.json
└── tsconfig.json

---

References

• ZBD Agent Docs
• @zbdpay/agent-fetch on npm
• @zbdpay/agent-pay on npm
• Vercel AI SDK
• Vercel KV