# ZapAPI — Bitcoin Lightning Payments API & AI Gateway

> ZapAPI is the Lightning-native payments platform. Developers accept Bitcoin Lightning payments with one REST API (invoices, payment links, subscriptions, checkout widget, webhooks), creators monetize with zaps, and teams call 500+ AI models paid per query in Bitcoin sats. Non-custodial by design: every project settles to its own settlement wallet — hosted, dedicated, or your own external wallet via Nostr Wallet Connect (NWC).

ZapAPI provides:
- A Lightning Payments REST API with a fully typed TypeScript SDK (`npm install @zapapi/sdk`), zero runtime dependencies, works in Node 18+, Deno, Bun, and the browser
- Hosted checkout pages and a drop-in checkout widget (one script tag) with WebLN + QR fallback
- Recurring subscription billing per project: weekly/monthly/yearly plans, trials, magic-link subscriber portal, grace → past_due → cancel dunning, renewals settled to the project's settlement wallet (including NWC wallets)
- Coupons & offers: code-gated discounts (coupon) and auto-applied discounts (offer) on invoices and payment links
- Gift cards: prepaid sats codes — paid issuance collects sats up front; recipients redeem real sats into their own wallet via LNURL-withdraw
- Project CRM: customers auto-built from settled payments (LTV, segments, tags)
- Refunds (payment refunds to BOLT11/lightning address, or credit notes)
- A Lightning Address marketplace: claim a free lightning address (you@zapapi.app) or buy premium domains, paid straight to providers over Lightning
- Creator tools: bio pages, tip jars, zaps (NIP-57), paywalled links, event tickets, paid calendar bookings, tabs, revenue splits
- An app directory for Lightning and nostr apps, ranked by real community zaps (sats), not votes
- An AI gateway: 500+ models (chat, image, video, TTS, STT, embeddings) through one OpenAI-compatible API, paid per query in Bitcoin sats over Lightning — no subscriptions

## Docs & API

- [Homepage](https://zapapi.app): Lightning Payments API for developers — overview, SDK quickstart, pricing
- [AI Models](https://zapapi.app/models): Live catalog of 500+ AI models with per-token pricing in Bitcoin sats
- [Documentation](https://docs.zapapi.app): Full API reference, guides, and SDK documentation

## Products

- [AI Gateway](https://zapapi.app/models): 500+ AI models (GPT, Claude, Gemini, Grok, DeepSeek, Llama, Qwen and more) via one OpenAI-compatible endpoint. Live per-token prices in sats; chat, vision, image generation, video, TTS, STT and embeddings. Top up from 100 sats with Lightning, NWC auto-topup, +5% Lightning bonus
- [AI Tools](https://zapapi.app/tools): Pay-per-call AI tools — image & video generation, TTS in 600+ languages, translation, OCR, comms. Every call quoted in sats upfront, destructive actions (SMS/calls/email) require explicit confirmation, automatic refunds on failures
- [Lightning Address Marketplace](https://zapapi.app/addresses): Search every lightning address provider in one place. Free first-party addresses (2100 sats/yr for extra), premium domains, works with every wallet, resolves for payments and nostr identity (NIP-05)
- [App Directory](https://zapapi.app/apps): Discover Lightning and nostr applications ranked by real sats from the community. Zap the apps you love, boost the ones you built
- [Profiles](https://zapapi.app/profiles): Public Lightning profiles and bio pages
- [Gift Cards](https://zapapi.app/gift-card): Redeem a prepaid sats gift card into any Lightning wallet (LNURL-withdraw)

## SDK Quickstart

```bash
npm install @zapapi/sdk
```

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

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

// Create a Lightning invoice — settles to the project's settlement wallet.
// Just an API key is enough when the key is project-scoped (no providerId).
const invoice = await zap.invoices.create({
  amount: 21000,
  description: 'Pro plan',
}, 'order-4821'); // idempotency key

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

Webhook signature verification (Express):

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

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

## Subscriptions Quickstart

```ts
// Create a recurring plan — renewals settle to the project's settlement wallet
const plan = await zap.plans.create({
  name: 'Pro',
  amountSats: 21000,
  interval: 'month',
  trialDays: 7,
});
// Hosted checkout: https://zapapi.app/subscribe/<plan.id>

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

## Discounts & Gift Cards Quickstart

```ts
// Coupon — customer enters at checkout; Offer — auto-applied in its window
await zap.discounts.create({ projectId, code: 'LAUNCH20', type: 'percent', percentOff: 20 });
await zap.discounts.create({ projectId, mode: 'offer', code: 'LAUNCH-WEEK', type: 'percent', percentOff: 15 });

// Discounted invoice — payer pays amount − discount
const invoice = await zap.invoices.create({ amount: 21000, description: 'Pro', couponCode: 'LAUNCH20' });

// Sell a gift card — buyer pays now; recipient redeems real sats via LNURL-withdraw
const { card, purchase } = await zap.giftCards.issue({ balanceSats: 21000, issueType: 'paid' });
const { lnurl } = await zap.giftCards.redeem(card.code, 21000); // public — code is the capability
```

## AI Gateway Quickstart

```bash
# OpenAI-compatible: point any OpenAI SDK at the AI base URL with a zap_* key
curl https://api.zapapi.app/api/v1/ai/chat/completions \
  -H "Authorization: Bearer zap_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-sonnet-5.5", "messages": [{"role": "user", "content": "Hello!"}]}'
```

- Public model catalog with live sats pricing: https://api.zapapi.app/api/v1/ai/public/models
- Variant suffixes on model ids: `:nitro` (fastest), `:floor` (cheapest), `:online` (web search), `:thinking`, `:free`
- Errors: 402 = insufficient AI credit (top up with Lightning), 404 = model not in catalog, 429 = rate limited. Failed upstream calls are never billed.

## Blog

- [Blog](https://zapapi.app/blog): Engineering deep-dives, Lightning Network guides, and product updates — Lightning invoices tutorials, non-custodial payments, NWC guides, webhooks