Lightning Gifts API

The app's own HTTP API: the routes the interface calls, the two credentials that open them, and the rules an integrator has to respect when real sats are moving.

Everything here is served by the same Next.js service that renders the site, under ${APP_URL}/api. Responses are JSON unless stated otherwise; an endpoint that fails answers with the matching HTTP status and, where the route has something to say, a plain-text body.

There is no versioned public API and no SDK. These are the routes in app/pages/api/, documented because the scheduler and the CLI probes depend on them — treat a route's name and shape as fixed, and read the source for anything not covered here.

Authentication

Three credentials reach these routes. Pick by who you are, not by convenience — the third one is an operator secret and grants everything.

A 401 means no credential was accepted; a 403 means the credential was fine but the caller is someone else (a user key may only act as its own user, and the admin routes require a SUPERADMIN UserRole row).

The scheduler's own binary still calls the internal spelling (/api/tipper/tips, /api/users, /api/reminders); the aliases accept the same parameters, so either path works. Only the operator-key routes below are operator-gated.

Gift statuses

Tip.status is the state machine everything else is built on. Two of these are money states for the recipient, and one of them is the reason a sender's dashboard groups the way it does.

UNFUNDED and UNSEEN are the only statuses a gift is created in. Expiry is not a status: it is the expiry timestamp on the gift, and only gifts in UNFUNDED, UNSEEN, SEEN or CLAIMED are eligible for the scheduler's reclaim.

Endpoint reference

Route names below are the public aliases. Every one of them re-exports the internal tip* route of the same shape (the pairing is in Vocabulary, and the payload fields keep their names). Only the paths changed; the behaviour is byte-identical. The exceptions: /api/claimTokens and /api/csp-report exist only under their public name — there is no internal twin to prefer.

Giver — the sender: any route below takes a session, or a user key acting as that user.

Recipient — the public routes take a session where one exists; the passphrase lookup deliberately does not.

Withdrawals — where sats actually leave.

Account — self-service, plus the two operator-only families.

Public and internal — no credential needed for the first three; the last one is deliberately dead.

Worked examples

Create a gift as the signed-in user (session cookie), then read your own list with a developer key.

# amount is in SATS (21000 sats below); currency is display metadata only
curl -sS -X POST "$APP_URL/api/gifts" \
  -H 'Content-Type: application/json' \
  -b "$SESSION_COOKIE" \
  -d '{
        "amount": 21000,
        "currency": "USD",
        "expiry": "2026-10-08T00:00:00.000Z",
        "onboardingFlow": "SKIP",
        "tippeeLocale": "en",
        "anonymousTipper": false,
        "generatePassphrase": false,
        "passphraseLength": 4
      }'

curl -sS "$APP_URL/api/gifts" -H "Authorization: Bearer $DEVELOPER_KEY"

Withdraw as the recipient. The rule that surprises integrators: the payout invoice must equal the exact sum of every withdrawable gift on the wallet — the app sweeps; it does not pay a partial amount, and a mismatch answers 500 "Withdrawal request does not match user/tip balance".

curl -sS -X POST "$APP_URL/api/invoices" \
  -H 'Content-Type: application/json' \
  -b "$SESSION_COOKIE" \
  -d '{"flow":"tippee","invoice":"<bolt11 for the exact sum>"}'
# 204 No Content on success; the HTTP status is the whole response body.

Drive the scheduler's two jobs by hand — the same calls the hourly job makes.

curl -sS -H "Authorization: Bearer $API_KEY" "$APP_URL/api/gifts?expired=true&reclaimable=true"
curl -sS -X POST -H "Authorization: Bearer $API_KEY" "$APP_URL/api/gifts/cklq1234/reclaim"
curl -sS -H "Authorization: Bearer $API_KEY" "$APP_URL/api/users?refundable=true&hasLightningAddress=true"

Rules that come from holding real money

Vocabulary, and the gift-speaking aliases

The product says gift, giver and recipient. The code, the database and the app's own client say *tip*, *tipper* and *tippee*: the Prisma model is Tip, the columns are tipperId, tippeeId and tipId. That is deliberate — renaming the data model buys nothing a user can see.

So most routes exist twice (/api/claimTokens and /api/csp-report are the single-spelling exceptions). The alias set below re-exports the internal handlers, so both spellings hit the same code and return byte-identical payloads, field names included (tipId, tipperId and tippeeId are what the JSON says whatever the route is called). Anything a third party reads should use the alias.