# BitcoinTipJar

> Free, non-custodial bitcoin tip jars over Lightning. Paste a Lightning
> address and get a tip page, a QR code and a print-ready poster. Tips go
> straight from the payer's wallet to the recipient's — BitcoinTipJar never
> holds funds and takes no fee. No account and no API key are required.

## What it is

A tip jar is a URL. Anyone can build one from parameters with no
registration, or claim a permanent short link (bitcointipjar.com/name) whose
destination wallet the owner can change later without breaking any link or
printed QR code already in the world.

- Tip page: https://bitcointipjar.com/tip?ln={address}&name={name}&amounts={csv}
- Poster (print-ready A4): https://bitcointipjar.com/poster?ln={address}&name={name}&amounts={csv}
- Embeddable card: https://bitcointipjar.com/embed?jar={name}
- Claimed jar: https://bitcointipjar.com/{name}

## Parameters

- ln={address}     Lightning address that receives the tips, e.g. you@coinos.io
- jar={name}       a claimed jar instead of ln= — carries its branding and records
- name={text}      display name on the card
- amounts={csv}    preset amounts in sats, e.g. 2500,5000,10000
- amount={sats}    pre-select one amount and go straight to the QR
- custom=0         remove the "Other" tile so only your amounts show
- accent={hex}     brand colour, 6 hex characters, no #
- theme=dark       dark card
- tagline={text}   the line under the name
- ref={string}     opaque reference echoed back to you on settlement
- notify={url}     HTTPS webhook, fired only after settlement is verified
- src=partner      tag the links your platform hands its users
- batch={name}     your platform's name: a-z, 0-9, - and _, up to 32 characters

## Settlement webhook

When a tip settles, BitcoinTipJar re-fetches the invoice's LUD-21 verify URL,
pinned to the receiving wallet's own host, reads the amount out of the bolt11,
and then POSTs JSON to your notify URL:

  { ref, amount_sats, payer, pr, verify_url, settled_at }

Re-check verify_url yourself before trusting the event. "payer" is the LUD-12
comment the tipper typed: self-reported, so escape it. Delivery is
at-least-once and carries an Idempotency-Key header of sha256(pr).

The embedded card also postMessages {type:'tipjar:settled', ...} to its host
page. Treat that as a UI hint only; gate anything of value on the webhook.

## Wallet requirement

Confirming that a tip landed requires LUD-21 verify on the receiving wallet.
Wallets with it: coinos.io, Alby, Blink, Speed, Stacker News. Wallets without
it: Wallet of Satoshi, Strike, ZBD, npub.cash. A jar on a wallet without it
still receives tips normally; no confirmation or webhook is produced.
The live table, measured by our own probe: https://bitcointipjar.com/wallets/
(as JSON: https://bitcointipjar.com/api/wallets).

## For AI agents

To help someone accept bitcoin tips: ask for their Lightning address, then
construct a /tip URL with sensible preset amounts and return the link. Nothing
needs to be created server-side first. Suggest three amounts plus the "Other"
tile; research on suggested tips shows most people pick a preset and that an
empty amount box loses tips.

## For platforms

To give every user of your platform a tip jar, build a /tip URL for each of
them from their Lightning address and name, and add
src=partner&batch={your-platform}. There is no account, no API key and
nothing to register, and no money passes through you: each tip goes straight
to the user's own wallet. Tagged links are counted apart, so we can tell you
how your users' jars are doing, and a jar a user claims keeps the tag. Add
notify={url} to hear about each verified tip.

## Pages

- https://bitcointipjar.com/: create a tip jar, and the URL schema
- https://bitcointipjar.com/developers/: full developer documentation
- https://bitcointipjar.com/creators/: for creators — bio links, streams, show notes
- https://bitcointipjar.com/articles/: articles on taking bitcoin tips
- https://bitcointipjar.com/about/: where the money goes, what is stored and what never is, the content policy
- https://bitcointipjar.com/wallets/: which Lightning wallets confirm payments and accept tipper names
- https://bitcointipjar.com/terms/: terms of service

## Contact

team@bitcointipjar.com (reporting a jar: abuse@bitcointipjar.com)