Playground Starter Kit

The ZBD + Next.js Playground Starter Kit is an application codebase that allows you to quickly get started with ZBD and Next.js. It includes two main sections: a ZBD API Playground and a Starter Kit for ZBD-powered Next.js applications.

Next.js

To use ZBD with Next.js and complete this guide, you will need the following:

1. Create a Next.js project

Start with a brand new Next.js project. To begin run the following command and walk through the initializing steps:

npx create-next-app@latest

2. Install @zbd/node Node.js SDK

Install ZBD:

3. Create Send and Receive API routes

Create a new file /app/api/receive/route.ts and add the following code to create an API route that will receive instant Bitcoin payments:

import { NextResponse } from 'next/server';
import { zbd } from "@zbd/node";

const ZBD_API_KEY = 'b7YW3s2JzZKGcXjIf5Dqof8wjKT2RuWr8';
const ZBD = new zbd(ZBD_API_KEY);

export async function POST() {
  try {
    const data = await ZBD.createCharge({
      amount: "100000", // 100 satoshis (100,000 msats)
      description: "Next.js + ZBD!",
    });

    return NextResponse.json(data);
  } catch (error) {
    return NextResponse.json({ error });
  }
}

Then create a new file /app/api/send/route.ts and add the following code to create an API route that will send Bitcoin Lightning Address payments:

import { NextResponse } from 'next/server';
import { zbd } from "@zbd/node";

const ZBD_API_KEY = 'b7YW3s2JzZKGcXjIf5Dqof8wjKT2RuWr8';
const ZBD = new zbd(ZBD_API_KEY);

export async function POST() {
  try {
    const data = await ZBD.sendLightningAddressPayment({
      lnAddress: "andre@zbd.gg", // Who is the recipient?
      amount: "100000", // 100 satoshis (100,000 msats)
      comment: "Next.js + ZBD!",
    });

    return NextResponse.json(data);
  } catch (error) {
    return NextResponse.json({ error });
  }
}

4. Run your Next.js server

Run the following command to start your Next.js server:

Using an API tool like Postman, you should be able to make a POST call to this endpoint and receive a JSON response with a payment request:

http://localhost:3000/api/request

You’re looking for the data.invoice.request property in the JSON response. It starts with lnbc1 and is the payment request anyone in the Bitcoin Lightning Network can use to pay you.

lnbc1u1pjdlax9pp5t7jhkd7h2wntd4f2v7xp22dknmjxp0q8nm7hfcny4p7a5mr7x3rsdp9f4hkueteypshggrfde6x2unwv46zqumsv4jkgcqzzsxqzjcsp5dsayu6m6632p28rnkeeqsr7d54amrkv6wh46yrv42gdgca8xl8gs9qyyssqgj2zrkax733rzulfkzc5mqsr8fpwrva82stpa7e0frw32722trv37jlq8mvlqfp8y75lr6mz63zd7qnxar8hhsehuy22pvfq6wjxwqqqa60lx3
Charges and payment requests are usually shown to users as QR codes that can be scanned by mobile apps (e.g. ZBD). Read Callbacks to understand how to receive updates about your payment asynchronously.

Using an API tool like Postman, you should be able to make a POST call to this endpoint and receive a JSON response with the payment success message:

http://localhost:3000/api/send

You’re looking for the status of completed to know that the payment settled successfully.

Payments in the Lightning Network are asynchronous so you may see a response stating the payment is processing. This is expected — use the callbackUrl property to receive updates about your payments.

5. Try it yourself

You can now send and receive instant Bitcoin payments using Next.js + ZBD!