Skip to content

Plain JavaScript ​

The framework components are thin views over createCheckout from @deadhop/client. Use it directly for Vue, Angular, Lit, Preact, web components or plain DOM code. Read Integrate payments into your app first: it explains the service values, who creates invoices, and why onPaid is not proof of payment.

Install ​

sh
npm install @deadhop/client      # npm
npx jsr add @deadhop/client      # JSR
deno add jsr:@deadhop/client     # Deno

A pay button without a framework ​

html
<button id="pay">Pay 5,000 sats</button>
<div id="invoice" hidden>
  <p id="status"></p>
  <a id="qr-link"><svg id="qr" width="220" height="220"><path /></svg></a>
  <code id="address"></code>
  <p id="expiry"></p>
</div>
ts
import { createDeadhop, createCheckout, invoiceView, progressMessage } from '@deadhop/client';

const deadhop = createDeadhop({ serverPubkey: 'npub1…', relays: ['wss://relay.example.com'] });
const checkout = createCheckout(deadhop, { onPaid: (inv) => console.log('paid', inv.id) });
const $ = (id: string) => document.getElementById(id)!;

checkout.subscribe((state) => {
  $('pay').hidden = state.phase !== 'idle' && state.phase !== 'error';
  $('invoice').hidden = state.invoice === null;
  if (!state.invoice) {
    $('status').textContent = progressMessage(state) ?? state.error?.message ?? '';
    return;
  }
  const v = invoiceView(state.invoice, state.now);
  $('status').textContent = v.statusLabel;
  $('address').textContent = v.address; // always textContent: never put service data in innerHTML
  $('expiry').textContent = v.expiry;
  $('qr-link').setAttribute('href', v.bip21);
  if (v.qr) {
    $('qr').setAttribute('viewBox', `0 0 ${v.qr.size} ${v.qr.size}`);
    $('qr').querySelector('path')!.setAttribute('d', v.qr.path);
  }
});

$('pay').addEventListener('click', () => checkout.create({ amount_sat: 5000, memo: 'Order 42' }));
// When the view goes away: checkout.destroy();

The address, amount and payment URI are validated before they reach subscribe: the QR code always pays exactly the address and amount shown.

The checkout ​

CallDoes
createCheckout(client, options)A checkout. Options: pollMs, onCreated, onDetected, onPaid, onError
checkout.create(input)Create an invoice (amount_sat, optional memo, expiry_secs) and follow it
checkout.watch(id)Follow an invoice that already exists, such as one your backend created
checkout.reset()Forget the invoice and go back to idle
checkout.destroy()Stop polling for good
checkout.subscribe(fn)Called at once and on every change; returns an unsubscribe function
checkout.getState()The current state: phase, invoice, error, now

phase is one of idle, creating (includes the proof of work), loading, pending, detected, confirmed, expired or error. An expired invoice is still polled, because a late payment can still arrive.

Rendering helpers ​

HelperGives
invoiceView(invoice, now)Status label, amounts in BTC and sats, memo, address, bip21, QR path and size, countdown, received summary, payable
progressMessage(state)Preparing invoice… and similar, before an invoice exists
LABELSThe English texts, to replace for another language
formatBtc, formatSats, parseSatsAmounts in and out

In other frameworks ​

subscribe follows the Svelte store contract, so a checkout plugs into most reactive systems:

ts
// Vue 3
const state = shallowRef(checkout.getState());
onUnmounted(checkout.subscribe((s) => (state.value = s)));

// Preact (or React without @deadhop/react)
const state = useSyncExternalStore(checkout.subscribe, checkout.getState);

// Angular
state = signal(checkout.getState());
constructor() { inject(DestroyRef).onDestroy(checkout.subscribe((s) => this.state.set(s))); }

Page security ​

Don't put service data into innerHTML; use textContent and attributes as above. The memo is written by whoever created the invoice, possibly a stranger. Your page needs connect-src wss: if it has a Content-Security-Policy; see Styling and page security.

deadhop 0.1.0 · Every page is also available as Markdown: replace .html with .md.