TypeScript SDK

npm install @zapapi/sdk

import { ZapAPI } from '@zapapi/sdk';

const zap = new ZapAPI(process.env.ZAPAPI_KEY); // zap_live_… or zap_test_…

// Create an invoice (BOLT11) — settles to the project's settlement wallet.
// With a project-scoped key (Dashboard → Project → API Keys), the API key
// is all you need — no projectId, no providerId.
const invoice = await zap.invoices.create(
  {
    amount: 21000,
    description: 'Pro plan',
  },
  'unique-idempotency-key', // safe retries — never double-charge
);

console.log(invoice.paymentRequest); // lnbc210n1…

const zap = new ZapAPI({
  apiKey: process.env.ZAPAPI_KEY,
  baseUrl: 'https://api.zapapi.com/v1', // override for self-hosted
  timeoutMs: 30_000,
  fetchFn: myFetch, // custom fetch (older Node, proxies, testing)
});

const zap = new ZapAPI('zap_test_…');
zap.isTestMode; // true

const invoice = await zap.invoices.create({
  amount: 25, // $25
  currency: 'USD',
  description: 'Pro plan',
});

console.log(invoice.amount);   // 30684 (sats)
console.log(invoice.fiatRate); // 81476.00 (USD/BTC at creation)

await zap.invoices.create(params, `order-${orderId}`);

const invoice = await zap.invoices.create(params, idempotencyKey?);
const one = await zap.invoices.get(id);
const { invoices, total } = await zap.invoices.list({ projectId, status, limit, offset });
const fresh = await zap.invoices.checkStatus(id);   // poll the settlement wallet
const cancelled = await zap.invoices.cancel(id);    // pending invoices only
const { qrCode } = await zap.invoices.getQRCode(id); // data URL for <img>

// Full repayment to the customer's lightning address
const refund = await zap.refunds.create(invoice.id, {
  destination: 'customer@wallet.com',
  reason: 'Customer requested cancellation',
});

// Partial repayment
await zap.refunds.create(invoice.id, { destination: '…', amountSats: 5000 });

// Credit note (record only — settle off-band)
await zap.refunds.create(invoice.id, { type: 'credit', amountSats: 5000 });

const forInvoice = await zap.refunds.listForInvoice(invoice.id);
const { refunds, total } = await zap.refunds.list({ limit: 50 });

const link = await zap.paymentLinks.create({
  description: 'Tip jar ☕',
  type: 'flexible',
  minAmount: 21,
  maxAmount: 100000,
});
// share link.paymentUrl — QR via zap.paymentLinks.getQRCode(link.id)

await zap.paymentLinks.updateStatus(link.id, 'disabled');
const all = await zap.paymentLinks.list();
await zap.paymentLinks.delete(link.id);

// Project customers — auto-built from settled invoices/payment links
const { customers } = await zap.customers.list({ projectId: 'proj_…', segment: 'vip' });
const customer = await zap.customers.get(id);
const stats = await zap.customers.stats('proj_…');
const top = await zap.customers.leaderboard(10);

// Create a plan on a project — renewals settle to the settlement wallet
const plan = await zap.plans.create({
  name: 'Pro',
  amountSats: 21000,
  interval: 'month',   // 'week' | 'month' | 'year'
  trialDays: 7,
  perks: ['Priority support'],
});
// Hosted checkout: https://zapapi.app/subscribe/<plan.id>
// Subscribers get a magic-link portal (pause / cancel / NWC auto-pay);
// failed renewals get a 3-day grace → past_due → cancel after 7 days.

const { subscriptions, total } = await zap.subscriptions.list({ status: 'active' });
const { mrrSats, arrSats, activeSubscribers } = await zap.subscriptions.revenue();
await zap.subscriptions.cancel(subscriptionId);

// Coupon — the customer enters the code at checkout
await zap.discounts.create({
  projectId: 'proj_…',
  code: 'LAUNCH20',
  type: 'percent',     // or 'amount' (fixed sats off)
  percentOff: 20,
  maxRedemptions: 100, // optional cap
});

// Offer — auto-applied at checkout in its window, no code needed
await zap.discounts.create({
  projectId: 'proj_…',
  mode: 'offer',
  code: 'LAUNCH-WEEK',
  type: 'percent',
  percentOff: 15,
  endsAt: '2026-11-04T00:00:00Z',
});

// The payer pays amount − discount; the discount is snapshotted on the invoice
const invoice = await zap.invoices.create({
  amount: 21000,
  description: 'Pro plan',
  couponCode: 'LAUNCH20',
});

// Sell a card — the buyer pays now into your settlement wallet;
// the card activates on settlement
const { card, purchase } = await zap.giftCards.issue({
  balanceSats: 21000,
  issueType: 'paid',   // or 'free' (merchant-funded comp cards)
});

// The recipient redeems real sats into their own wallet
// (public — the code is the capability)
const { lnurl, remainingSats } = await zap.giftCards.redeem(card.code, 21000);
// → show lnurl as a QR; their wallet pulls the sats (LNURL-withdraw)

const endpoint = await zap.webhookEndpoints.create({
  url: 'https://api.yourapp.com/hooks/zapapi',
  events: ['invoice.paid', 'zap.received'],
  projectId: 'proj_…',
});
// ⚠️ endpoint.secret is returned EXACTLY ONCE — store it for verification

const all = await zap.webhookEndpoints.list({ projectId: 'proj_…' });
await zap.webhookEndpoints.updateStatus(endpoint.id, 'disabled');
await zap.webhookEndpoints.delete(endpoint.id);

import express from 'express';
import { ZapAPI } from '@zapapi/sdk';

const app = express();

app.post(
  '/webhooks/zapapi',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const ok = ZapAPI.webhooks.verify(
      req.body.toString(),
      req.headers['x-zapapi-signature'] as string,
      process.env.ZAPAPI_WEBHOOK_SECRET!,
    );
    if (!ok) return res.sendStatus(400);

    const event = JSON.parse(req.body.toString());
    switch (event.type) {
      case 'invoice.paid':
        // fulfill the order — event.data.paymentHash, event.data.preimage
        break;
      case 'zap.received':
        // someone zapped you — event.data.amountSats, event.data.senderPubkey
        break;
    }
    res.json({ received: true });
  },
);

import { ZapAPI, ZapAPIError } from '@zapapi/sdk';

try {
  await zap.invoices.create(params);
} catch (err) {
  if (err instanceof ZapAPIError) {
    err.status;         // 400, 401, 403, 409, 429, …
    err.code;           // machine-readable code when available
    err.payload;        // raw API error body
    err.isUnauthorized; // 401 — bad/expired key
    err.isForbidden;    // 403 — missing scope
    err.isNotFound;     // 404
    err.isConflict;     // 409 — idempotency conflict
    err.isRateLimited;  // 429 — slow down
  }
}

// Browse the live catalog
const models = await zap.ai.listModels('chat');

// Non-streaming completion
const completion = await zap.ai.completions.create({
  model: 'anthropic/claude-sonnet-5.5',
  messages: [{ role: 'user', content: 'Hello!' }],
});

// Streaming (async generator of text deltas)
for await (const delta of zap.ai.completions.stream({
  model: 'openai/gpt-6-luna',
  messages: [{ role: 'user', content: 'Write a haiku about Lightning' }],
  stream: true,
})) {
  process.stdout.write(delta);
}

// Balance, topups, usage
const balance = await zap.ai.getBalance();     // sats
const topup = await zap.ai.createTopup(5000);  // Lightning invoice
await zap.ai.checkTopup(topup.id);             // credits when paid
const usage = await zap.ai.getUsageSummary();  // spend + top models

// NWC auto-topup (never hit a 402)
await zap.ai.saveAutoTopup({
  nwcConnectionId: 'conn-uuid',
  thresholdSats: 500,
  topupSats: 5000,
  dailyCapSats: 20000,
});