# deadhop
> Accept on-chain bitcoin payments without exposing a server.
**Nothing to reach. Nothing to spend.**
deadhop creates bitcoin invoices, watches the chain and reports payments. Customers and operators reach it only through Nostr relays. It opens no ports and holds no spending keys.
## How a payment flows
### Nothing to connect to
The service only dials out, to Nostr relays. There is no listening socket, HTTP endpoint or login form, so there is nothing to port-scan, nothing to DDoS by IP and no web stack to exploit.
### Relays carry ciphertext
Requests and responses are ContextVM (MCP over Nostr), NIP-44 encrypted and gift-wrapped (NIP-59). Relays forward them without being able to read or alter them. Plaintext requests are refused.
### Proof of work on public invoices
A non-operator who creates an invoice must mine NIP-13 proof of work into the signed request. The work is bound to the caller’s key, to this service and to one use. Rate limits and daily caps apply after it.
### Watch-only: it cannot spend
The service holds only an account public key (xpub). It derives a fresh native segwit address for every invoice. Taking over the server does not move funds already received.
### Confirmed by your own node
Payments are read from your Electrum server (Fulcrum or electrs). The service re-hashes every transaction it is given, counts confirmations itself, and pins the chain’s genesis block on every reconnect.
## Security benefits
- **No IP address to attack.** Outbound connections only. Run it behind a VPN or Tor and relays see the exit, not you.
- **End-to-end encryption.** NIP-44 with NIP-59 gift wrap. Relays can see that someone talks to the service key, when and how much, but not what is said.
- **No passwords or accounts.** Callers are identified by the Nostr key that signed the request. Operators are a list of public keys.
- **Strictly typed interface.** Every tool has published JSON schemas. Unknown fields are rejected; the dashboard validates every response with strict schemas.
- **Proof of work and rate limits.** NIP-13 work for public invoice creation, per-key and global budgets, open-invoice and daily caps.
- **Replay protection.** Every invoice request must be fresh, addressed to this service and never seen before, operators included.
- **Cannot spend.** Watch-only BIP-84 wallet. A compromised host cannot move funds already received.
- **Verified payment data.** Transactions are re-hashed against their ids, sums are capped, and one bad invoice cannot stall the others.
- **Small, tested code.** One Rust binary, no HTTP stack, SQLite. 100% line and function coverage, plus end-to-end tests on regtest.
- **Remote control without remote risk.** Operators manage relays, proxy, limits and keys from the dashboard. Every change is one-time, audited, and can never touch the wallet or the Electrum server.
- **Hardened dashboard.** Static Svelte page with a strict Content-Security-Policy, frame refusal and text-only rendering of server data.
## What it does not protect against
- Your Electrum server is trusted. Run your own and keep it on a private network.
- Public invoicing slows abuse down but a determined attacker can still degrade it. A shop back end can hold an operator key instead.
- Relays see metadata: timing, sizes and the IP that connects. Use a VPN or Tor.
- Only “confirmed” means paid. Use more confirmations for larger amounts.
## What you run
- **Service:** Rust. One binary, SQLite, watch-only wallet.
- **Dashboard:** Svelte. Checkout, plus health, statistics, settings and backups for operators. Sign in with a Nostr key.
- **Your node:** Any Electrum server: Fulcrum or electrs next to Bitcoin Core.
**Price:** Self-hosted software. No fees, no custodian, no account.
## Questions
**Who can create an invoice?**
By default only operators, identified by the Nostr public keys you list. You can also allow the public to create invoices; each public request then has to carry proof of work and is rate limited.
**Do I log in?**
No accounts or passwords. The dashboard signs each request with your Nostr key, from a browser extension or a pasted key.
**Can a compromised server spend my bitcoin?**
No. The service holds only an account public key (xpub), so it can derive addresses but cannot sign transactions.
**What do I need to run it?**
The deadhop binary, a few Nostr relays, and an Electrum server (Fulcrum or electrs) on your own Bitcoin node. The dashboard is a static page you can host anywhere.
## Documentation
- [Quick start](/docs/quickstart.md): Run the full stack on regtest and pay an invoice.
- [How it works](/docs/how-it-works.md): Architecture, invoice states, who can create invoices.
- [Configuration](/docs/configuration.md): Every environment variable and its default.
- [Deployment](/docs/deployment.md): Service, dashboard and network placement.
- [Tools API](/docs/api.md): Invoicing and operator tools: inputs, outputs and errors.
- [Security](/docs/security.md): Threat model, findings and the risks you accept.
---
Source: https://deadhop.run/docs/
# deadhop documentation
> deadhop accepts on-chain bitcoin payments from a service that has no public address. Clients reach it only through Nostr relays using ContextVM.
deadhop creates on-chain bitcoin invoices, watches the chain and reports payments, like a
BTCPay-style server does for simple invoicing. It never listens on a port. Customers and
operators reach it only through Nostr relays, using [ContextVM](https://contextvm.org)
(MCP over Nostr), so an attacker has no IP address, HTTP endpoint or login form to aim at.
## What you get
- **A fresh address per invoice**, derived from a watch-only BIP-84 account key. The
service cannot spend.
- **Payment detection and confirmation tracking** against your own Electrum server.
- **A static Svelte dashboard** for checkout and for operators. Sign in with a Nostr key;
there are no accounts.
- **Strictly typed tools** over end-to-end encrypted Nostr messages: five for invoicing,
twelve for operators (health, statistics, settings, keys, control, backups).
## Components
| Part | Technology | Role |
| --- | --- | --- |
| Service (`server/`) | Rust, one binary (about 8 MB), SQLite | Issues invoices, polls the chain, answers requests |
| Dashboard (`dashboard/`) | Svelte 5 static page | Checkout for customers, overview for operators |
| Chain backend | Fulcrum or electrs | Reports transactions for each invoice address |
| Transport | Any Nostr relays | Carries encrypted requests and responses |
```
customer / operator relays your machine
┌──────────────────┐ wss ┌────────────┐ wss ┌──────────────────────────┐
│ Svelte dashboard ├──────►│ Nostr │◄──────┤ deadhop (Rust) │
│ Nostr identity │ │ relay(s) │ │ outbound only │
│ NIP-44 + NIP-13 │ │ ciphertext │ │ watch-only xpub, SQLite │
└──────────────────┘ └────────────┘ └────────────┬─────────────┘
│ Electrum protocol
┌───────▼────────┐
│ Fulcrum/electrs│
└────────────────┘
```
## Where to go next
- [Quick start](./quickstart.md): run everything on regtest and pay an invoice.
- [How it works](./how-it-works.md): data flow, invoice states, who can create invoices.
- [Configuration](./configuration.md) and [Deployment](./deployment.md): run it for real.
- [Integrate into your app](./integrate.md): pay buttons and invoices, with a guide each for
[React](./integrate-react.md), [Solid](./integrate-solid.md),
[Svelte 5](./integrate-svelte5.md), [Svelte 4](./integrate-svelte4.md),
[plain JavaScript](./integrate-javascript.md) and your [backend](./integrate-backend.md).
- [Tools API](./api.md): invoicing and operator tools, for building your own client.
- [Security](./security.md): threat model, findings and the risks you accept.
---
Source: https://deadhop.run/docs/quickstart.html
# Quick start
> Run deadhop, its dashboard, bitcoind, Fulcrum and a private relay on a local regtest chain, then create and pay an invoice.
Run the whole system on a throwaway regtest chain, on loopback only.
## Requirements
- Rust 1.88 or newer
- Node 22 or newer
- Docker
- [`just`](https://github.com/casey/just)
## Start it
```sh
just up # regtest bitcoind + Fulcrum + private relay, a funded "miner" and a "merchant" wallet
just server # builds and runs deadhop; writes dashboard/public/config.json
just dashboard # serves the dashboard at http://127.0.0.1:4173
```
Run `npm install` in `dashboard/` once before `just dashboard`.
## Pay an invoice
1. Open http://127.0.0.1:4173 and choose **Continue as guest**.
2. Enter an amount and choose **Create invoice**. The page mines proof of work, then shows
the QR code and address.
3. Pay it from the regtest miner wallet. This also mines one block:
```sh
just pay
```
4. The page moves to *Payment seen* and then *Paid* on its own.
5. Sign in as the operator by pasting the key in `data/dev/operator.nsec` to see the
operator dashboard. To use your own key instead, add it under **Settings → Operators**,
or put `DEADHOP_ADMINS=npub1…` in `.env.local` (gitignored; the dev scripts read it on every run). Any other key only
gets the invoice form.
## Stop it
```sh
just down # removes the stack and its chain data
```
The development stack uses unpinned images and no authentication. Never use it as a
production deployment; see [Deployment](./deployment.md).
---
Source: https://deadhop.run/docs/how-it-works.html
# How it works
> How deadhop receives requests over Nostr, checks proof of work, derives addresses, detects payments and moves invoices between states.
## Request path
1. A client (the dashboard, or your own) builds an MCP request and signs it as a Nostr event
of kind 25910 (ContextVM).
2. The event is NIP-44 encrypted to the service's key and gift-wrapped (NIP-59), then
published to the relays the service listens on.
3. The service, which holds open outbound websocket connections to those relays, receives
it, unwraps it and identifies the caller by the key that signed the inner event.
4. The service checks admission (see below), runs the tool, and sends back an encrypted,
gift-wrapped response the same way.
Plaintext requests are refused. The service never accepts an inbound connection.
| Concern | Mechanism |
| --- | --- |
| Reachability | Only outbound websocket connections to relays |
| Confidentiality | NIP-44 encryption with NIP-59 gift wrap on every message |
| Identity | The Nostr key that signed the request; operators are a configured list of keys |
| Typed interface | MCP tools with published JSON schemas (five for invoicing, twelve for operators); unknown fields are rejected |
| Abuse resistance | NIP-13 proof of work for public invoice creation, then rate limits and caps |
| Funds | Watch-only account public key; one fresh native segwit address per invoice |
| Payment detection | Polls an Electrum server per open invoice, re-hashes every transaction, counts confirmations |
## Who can create invoices
You choose with `DEADHOP_PUBLIC_INVOICING`.
**Off (the default): operators only.** An operator is a Nostr public key listed in
`DEADHOP_ADMINS` (hex, `npub` or `nprofile`), or added from the dashboard by another
operator. There is no account or password: the dashboard signs each request with
the operator's key, and the service checks the signature against the list. Use this when you
hand out invoices yourself, or when a shop back end holds an operator key and creates
invoices for customers.
**On: anyone can request one.** The dashboard's **Continue as guest** creates a throwaway key
in the browser. Each public `create_invoice` must carry proof of work
(`DEADHOP_POW_BITS`, default 20) and is subject to per-key and global rate limits, a cap on
open invoices and a daily cap. The public cannot request a lifetime longer than the
default.
In both modes:
- `list_invoices` and `get_stats` are operator-only.
- `get_invoice` works for anyone who holds the invoice's 128-bit random id. The id is the
capability, so customers see only the invoices they were given.
- Paying never touches the service: the customer sends bitcoin to the address.
## Proof of work
The client mines a NIP-13 `nonce` tag into the request event itself before signing it.
The tag commits to the target difficulty. The service accepts the event only if all of
these hold:
- it is signed by the caller and is of the ContextVM kind;
- it is addressed to this service (`p` tag);
- it is fresh, within `DEADHOP_POW_WINDOW_SECS` (default 600 s);
- it has never been used before;
- it meets the difficulty, both the committed target and the required one.
Operators skip only the difficulty check. The others apply to them too, so a captured
operator request cannot be replayed.
## Addresses
`DEADHOP_XPUB` is a BIP-84 account key (`xpub`/`zpub`, or `tpub`/`vpub` on test networks).
Leave it unset under Compose and the offline `wallet` service generates a 24-word wallet,
keeps the phrase to itself (no network, its own volume) and passes only the account key on;
`deadhop wallet export` prints the phrase so the funds can be spent from any wallet app.
Invoice *n* gets the P2WPKH address at `0/n` on that account. Index allocation is atomic in
SQLite, so two invoices never share an address.
## Payment detection
Every `DEADHOP_POLL_SECS` (default 10 s) the service asks the Electrum server for the
history of each open invoice's script, plus the chain tip. For each transaction it:
- checks that the raw transaction hashes to the txid it was given;
- counts each transaction once, even if the server lists it twice;
- sums outputs to the invoice address, capped at the bitcoin supply;
- computes confirmations from the transaction's height and the tip.
Each invoice is evaluated on its own. One that cannot be read keeps its last known amounts
and is counted in `watch_errors`, and the others carry on. On every reconnection the
service checks the Electrum server's genesis block against `DEADHOP_NETWORK`.
## Invoice states
| State | Meaning |
| --- | --- |
| `pending` | Waiting for payment |
| `detected` | The full amount has been seen, not yet with enough confirmations |
| `confirmed` | The full amount has at least `DEADHOP_MIN_CONFIRMATIONS` confirmations. Final. |
| `expired` | The lifetime passed before the full amount was seen |
An unconfirmed payment that disappears (replaced or double-spent) moves a `detected`
invoice back. Expired invoices are still watched for `DEADHOP_LATE_GRACE_SECS` (default one
day), so a late payment that covers the amount still moves the invoice to `detected` and then
`confirmed`.
`detected` means *seen*, not *paid*. Release goods only on `confirmed`.
---
Source: https://deadhop.run/docs/configuration.html
# Configuration
> Every deadhop environment variable, its default and what it controls, plus the startup checks the service performs.
All configuration is environment variables. Nothing has a network-reaching default.
| Variable | Default | Meaning |
| --- | --- | --- |
| `DEADHOP_RELAYS` | required | Comma-separated `wss://` relay URLs |
| `DEADHOP_ELECTRUM` | required | Electrum server: `host:port` (plain TCP) or `tls://host:port` |
| `DEADHOP_ELECTRUM_CERT_SHA256` | none | Pin the server's TLS certificate: SHA-256 fingerprint(s), comma-separated |
| `DEADHOP_XPUB` | see below | Your wallet's BIP-84 **account** key (`xpub`/`zpub`, or `tpub`/`vpub` on test networks). Unset: one is generated (Compose) |
| `DEADHOP_XPUB_FILE` | none | Read the account key from this file when `DEADHOP_XPUB` is unset (the wallet service writes it) |
| `DEADHOP_NETWORK` | `bitcoin` | `bitcoin`, `testnet`, `signet` or `regtest` |
| `DEADHOP_ADMINS` | none | Comma-separated operator public keys (hex or `npub`) |
| `DEADHOP_PUBLIC_INVOICING` | `false` | Let non-operators create invoices (with proof of work) |
| `DEADHOP_POW_BITS` | `20` | NIP-13 difficulty for non-operators |
| `DEADHOP_POW_WINDOW_SECS` | `600` | Accepted age and clock skew of a request event |
| `DEADHOP_MIN_CONFIRMATIONS` | `1` | Confirmations before `confirmed` |
| `DEADHOP_DEFAULT_EXPIRY_SECS` | `3600` | Invoice lifetime when none is requested |
| `DEADHOP_MAX_EXPIRY_SECS` | `86400` | Longest lifetime an operator may request |
| `DEADHOP_MIN_AMOUNT_SAT` | `1000` | Smallest invoice |
| `DEADHOP_MAX_AMOUNT_SAT` | `100000000` | Largest invoice |
| `DEADHOP_MAX_OPEN_INVOICES` | `500` | Open invoices before the public is refused |
| `DEADHOP_MAX_INVOICES_PER_DAY` | `2000` | Invoices (address indices) per 24 h before the public is refused |
| `DEADHOP_RATE_GLOBAL_PER_MIN` | `30` | Public invoice creations per minute, all callers |
| `DEADHOP_RATE_PER_KEY_PER_MIN` | `6` | Public invoice creations per minute, per key |
| `DEADHOP_RATE_REQUESTS_PER_MIN` | `1200` | Public tool calls per minute, all callers |
| `DEADHOP_RATE_REQUESTS_PER_KEY_PER_MIN` | `120` | Public tool calls per minute, per key |
| `DEADHOP_POLL_SECS` | `10` | Chain polling interval |
| `DEADHOP_LATE_GRACE_SECS` | `86400` | How long expired invoices are still watched |
| `DEADHOP_DATA_DIR` | `data` | Database and the service's Nostr key (created `0700`) |
| `DEADHOP_ANNOUNCE` | `false` | Publish public ContextVM discovery announcements |
| `DEADHOP_NAME` | `deadhop` | Name shown in the dashboard |
| `DEADHOP_PROXY` | none | Proxy for relay connections only: `socks5://`, `https://` or `http://`, optionally `user:pass@` |
| `DEADHOP_PROXY_LOCKED` | `false` | Refuse proxy changes from the dashboard |
| `DEADHOP_LOG` | `warn,deadhop=info,contextvm_sdk=off,rmcp=off` | Log filter |
At least one of `DEADHOP_ADMINS` or `DEADHOP_PUBLIC_INVOICING=true` is required.
`DEADHOP_ADMINS` accepts hex, `npub` and `nprofile` keys, with or without `nostr:`.
## Changing settings from the dashboard
Operators can change the relays, proxy, proof of work, rate limits, amount and lifetime
limits, confirmations, caps, polling, the late-payment grace and the PayJoin/CoinJoin
policy at runtime, and add or remove operator keys. Changes are stored in the database as
overrides on top of the environment and survive restarts. *Reset to environment* drops
them all.
- A new relay list or proxy reconnects the service. If no relay connects within 30
seconds, the previous ones are restored.
- Values are checked against the same bounds as the environment.
- If the environment later changes so that stored overrides no longer fit, they are
ignored and a warning is shown.
- These stay host-only: `DEADHOP_XPUB`, `DEADHOP_NETWORK`, `DEADHOP_ELECTRUM`,
`DEADHOP_DATA_DIR`, `DEADHOP_ANNOUNCE` and the keys in `DEADHOP_ADMINS`. With
`DEADHOP_PROXY_LOCKED=true` the proxy is host-only too.
## Electrum over TLS
For an Electrum server that is not on this machine, use its TLS port and pin its
certificate:
```sh
deadhop fingerprint node.lan:50002 # prints the certificate's SHA-256 and the settings below
export DEADHOP_ELECTRUM=tls://node.lan:50002
export DEADHOP_ELECTRUM_CERT_SHA256=
```
- The command trusts whatever answers, so compare the fingerprint with the certificate on
the node, for example `openssl x509 -in -noout -fingerprint -sha256`.
- A pinned certificate is accepted whatever its name, issuer or expiry, which suits
self-signed Fulcrum certificates. The server must still prove it holds the
certificate's private key, on every connection.
- List two fingerprints, comma-separated, while rotating a certificate.
- Without a pin, `tls://` checks the certificate against the public authorities (and the
service warns that it is not pinned).
- A certificate that does not match stops the service at startup and fails every
reconnection.
## Proxy
Only connections to Nostr relays go through the proxy; the Electrum server is always
reached directly.
| Form | Use |
| --- | --- |
| `socks5://127.0.0.1:9050` | Tor or a VPN's SOCKS server; host names are resolved by the proxy, so `.onion` relays work |
| `https://user:pass@proxy.example:443` | An HTTPS proxy (TLS to the proxy, checked against the public web roots, then `CONNECT`) |
| `http://127.0.0.1:3128` | A plain HTTP `CONNECT` proxy on this machine or a private network |
Operators are exempt from proof of work and rate limits. The public cannot request a
lifetime longer than `DEADHOP_DEFAULT_EXPIRY_SECS`.
## Startup checks
- **Identity.** On first start the service creates its Nostr key in
`/server.nsec` (mode `0600`) and writes the public key to
`/server.pubkey`. It refuses to start if the key file is readable by others.
- **Chain.** It refuses to start if the Electrum server's genesis block does not match
`DEADHOP_NETWORK`.
- **Warnings.** It logs a warning for a remote Electrum server, weak proof of work with
public invoicing on, and `ws://` relays on mainnet.
- **First address.** It logs the receive address at index 0. Confirm that your wallet shows
that exact address before taking real payments. A wrong account key (for example BIP-49
instead of BIP-84) still produces valid addresses, but your wallet will not show payments
to them.
## Example
```sh
export DEADHOP_RELAYS=wss://relay.one.example,wss://relay.two.example
export DEADHOP_ELECTRUM=127.0.0.1:50001
export DEADHOP_XPUB=zpub... # BIP-84 account key, public only
export DEADHOP_ADMINS=npub1... # your operator key
export DEADHOP_MIN_CONFIRMATIONS=2
deadhop
```
---
Source: https://deadhop.run/docs/deployment.html
# Deployment
> Run deadhop in production. Supervise the service, host the static dashboard with security headers, and place it behind a VPN or Tor with your own Electrum server.
## 1. The service
1. Build it: `cargo build --release` in `server/` produces `target/release/deadhop`.
2. Configure it with environment variables (see [Configuration](./configuration.md)).
3. Run it as its own user under a supervisor such as systemd with `Restart=always`. If the
request loop ever stops, the process exits with an error instead of staying up while
answering nobody.
4. Back up the data directory with its permissions intact. It holds the SQLite database and
the service's Nostr key.
Example systemd unit:
```ini
[Unit]
Description=deadhop
After=network-online.target
Wants=network-online.target
[Service]
User=deadhop
EnvironmentFile=/etc/deadhop/env
WorkingDirectory=/var/lib/deadhop
ExecStart=/usr/local/bin/deadhop
Restart=always
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/deadhop
PrivateTmp=true
[Install]
WantedBy=multi-user.target
```
## 2. The dashboard
```sh
cd dashboard && npm ci && npm run build
```
Serve `dashboard/dist/` from any static host, with a `config.json` next to `index.html`
(see `public/config.example.json`) holding the service's public key and the relay list.
The page ships a strict Content-Security-Policy and makes no requests other than
`config.json` and the relay websockets. It refuses to run inside a frame and shows the
service key it is talking to in its footer, so it can be compared with the one you publish.
Have the web server add these headers (a `` policy cannot express the first):
```
Content-Security-Policy: frame-ancestors 'none'
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
```
## 3. Network placement
- **Hide the service's address.** Run it behind a VPN or Tor so relays see the exit, not
you: route the whole host, or set `DEADHOP_PROXY` (for example `socks5://127.0.0.1:9050`
for Tor) for relay connections. Add `DEADHOP_PROXY_LOCKED=true` so that an operator key
cannot swap in a proxy that reveals your address. The service needs outbound access to
the relays and the Electrum server only; drop all inbound traffic.
- **Use your own Electrum server.** Fulcrum or electrs on your node, on the same host or a
private network; across a network, use `tls://` with a pinned certificate (see
[Configuration](./configuration.md#electrum-over-tls)). A third-party server learns
every address you issue and decides what you believe was paid.
- **Use more than one relay**, prefer relays you run, and use `wss://` only.
## Checklist
- [ ] Electrum server is your own and reachable only locally or over a private network
- [ ] If it is not on the same machine: `tls://` with a pinned `DEADHOP_ELECTRUM_CERT_SHA256`
- [ ] Either `DEADHOP_XPUB` is your wallet's BIP-84 account key and the first receive
address logged at startup appears in that wallet, or the wallet was generated and its
recovery phrase has been exported (`deadhop wallet export`) and stored offline
- [ ] Wallet gap limit raised if public invoicing is on
- [ ] Public invoicing off unless you need it; `DEADHOP_POW_BITS` at 20 or more if on
- [ ] `DEADHOP_MIN_CONFIRMATIONS` chosen for your amounts
- [ ] Service runs as its own user, behind a VPN or Tor, with inbound traffic dropped
- [ ] A supervisor restarts the process if it exits
- [ ] Two or more relays, at least one you control, all `wss://`
- [ ] Data directory backed up with its permissions intact
- [ ] Dashboard served over HTTPS with the headers above
- [ ] Operators use a browser extension and a key made only for this service
- [ ] Someone watches for `chain_ok = false` and `watch_errors > 0` in the operator view
- [ ] `DEADHOP_PROXY` and `DEADHOP_PROXY_LOCKED=true` set on the host if the service's location
must stay hidden even from someone holding an operator key
- [ ] Backups in `/backups` are copied off the host regularly
## Testing against a real Electrum server
A read-only smoke test asks a server for its genesis hash and chain tip. Put the host in the
gitignored `.env.local`:
```sh
# .env.local: DEADHOP_TEST_ELECTRUM_HOST=... [DEADHOP_TEST_ELECTRUM_PORT=50001]
just live-electrum
```
---
Source: https://deadhop.run/docs/api.html
# Tools API
> Reference for the deadhop MCP tools served over ContextVM, for invoicing and for operator management, with inputs, outputs and error codes.
deadhop is an MCP server reached over Nostr with [ContextVM](https://contextvm.org).
Any MCP client that speaks the ContextVM transport can call it. Results come back as MCP
`structuredContent` that matches each tool's published output schema.
## Connecting
You need the service's public key (`/server.pubkey`) and its relay list. With the
TypeScript SDK:
```ts
import { Client } from '@contextvm/mcp-sdk/client/index.js';
import { EncryptionMode, NostrClientTransport, PrivateKeySigner } from '@contextvm/sdk';
const transport = new NostrClientTransport({
signer: new PrivateKeySigner(myHexSecretKey),
relayHandler: ['wss://relay.one.example'],
serverPubkey: SERVICE_PUBKEY_HEX,
encryptionMode: EncryptionMode.REQUIRED, // the service refuses plaintext
});
const client = new Client({ name: 'my-shop', version: '1.0.0' });
await client.connect(transport);
const info = await client.callTool({ name: 'get_info', arguments: {} });
```
A non-operator calling `create_invoice` must mine NIP-13 proof of work into the signed
request event: add a `["nonce", "", ""]` tag and vary the counter until
the event id has at least `pow_bits` leading zero bits. The dashboard's `src/lib/pow.ts` is a
working implementation that wraps any signer.
## Tools
All inputs reject unknown fields.
### `get_info`
Anyone. No arguments. Returns the service parameters for this caller.
| Field | Type | Meaning |
| --- | --- | --- |
| `name`, `version` | string | Service name and version |
| `network` | string | `bitcoin`, `testnet`, `signet` or `regtest` |
| `public_invoicing` | boolean | Whether non-operators may create invoices |
| `pow_bits` | integer | Required proof of work for non-operators |
| `pow_window_secs` | integer | Accepted age of a request event |
| `min_confirmations` | integer | Confirmations before `confirmed` |
| `default_expiry_secs` | integer | Lifetime when none is requested |
| `max_expiry_secs` | integer | Longest lifetime this caller may request |
| `min_amount_sat`, `max_amount_sat` | integer | Amount bounds |
| `is_admin` | boolean | Whether the caller is an operator |
### `create_invoice`
Operators, and the public when `public_invoicing` is on (with proof of work).
| Argument | Type | Meaning |
| --- | --- | --- |
| `amount_sat` | integer, required | Amount in satoshis, within the bounds above |
| `memo` | string, optional | Note stored with the invoice, at most 200 characters, no control or invisible characters |
| `expiry_secs` | integer, optional | Lifetime in seconds, from 60 up to `max_expiry_secs` |
Returns an **Invoice**:
| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | 32 lowercase hex characters (128 random bits). Whoever holds it can read the invoice. |
| `address` | string | Fresh native segwit address |
| `amount_sat` | integer | Requested amount |
| `memo` | string | Note, empty if none |
| `status` | string | `pending`, `detected`, `confirmed` or `expired` |
| `received_sat` | integer | Total seen, confirmed or not |
| `confirmed_sat` | integer | Total with enough confirmations |
| `created_at`, `expires_at` | integer | Unix seconds |
| `settled_at` | integer or null | When it became `confirmed` |
| `bip21` | string | `bitcoin:` URI with address and amount |
| `confirmations_required` | integer | Confirmations this invoice needs |
### `get_invoice`
Anyone holding the id. Argument: `id` (32 lowercase hex characters). Returns an Invoice.
### `list_invoices`
Operators only. Newest first.
| Argument | Type | Meaning |
| --- | --- | --- |
| `status` | string, optional | Only invoices in this state |
| `before` | integer, optional | Only derivation indices below this (pagination cursor) |
| `limit` | integer, optional | Page size, 1 to 200, default 50 |
Returns `{ invoices, next_before }`. Each entry is an Invoice plus `index` (derivation index)
and `creator` (hex key that created it). Pass `next_before` as `before` for the next page; it
is absent on the last page.
### `get_stats`
Operators only. No arguments.
| Field | Type | Meaning |
| --- | --- | --- |
| `pending`, `detected`, `confirmed`, `expired` | integer | Invoice counts per state |
| `confirmed_sat`, `detected_sat` | integer | Amounts in those states |
| `next_index` | integer | Next derivation index |
| `tip_height` | integer or null | Last chain tip seen |
| `last_poll_at` | integer or null | Unix seconds of the last poll |
| `chain_ok` | boolean | Whether the last poll reached the chain backend |
| `watch_errors` | integer | Invoices that could not be read in the last poll |
## Management tools
Operators only. Every tool that changes something needs a fresh request event addressed
to this service that was never used before (ids are remembered across restarts) and is
recorded in the audit log.
| Tool | Arguments | Returns |
| --- | --- | --- |
| `get_health` | none | `service` (version, start, uptime, online since, paused, restarts), `relays` (url, status, connected), `proxy` (password hidden), `chain`, `database` (integrity, size, invoices, backups), `warnings` |
| `get_metrics` | none | `addresses_created`, `invoices`, `payments`, `received_sat`, `windows` for `24h`, `7d`, `30d`, `365d` with `available` (false until the service has been online that long), `sweep` status |
| `get_payment_series` | `range`: `day`, `week`, `month` or `year` | `points` of `{ start, count, sat }`: 24 hourly, 7 or 30 daily, or 52 weekly buckets, gap-filled |
| `get_settings` | none | `settings` (live), `defaults` (environment), `overridden` (names), `fixed` (host-only values), `operators`, `restart_pending`, `warnings` |
| `update_settings` | `patch`: only the settings to change; `sweep` may be partial; `proxy: ""` turns the proxy off | Same as `get_settings` |
| `reset_settings` | none | Same as `get_settings` |
| `add_operator` | `pubkey` (hex, `npub` or `nprofile`), optional `label` | Same as `get_settings` |
| `remove_operator` | `pubkey` | Same as `get_settings`; environment keys are refused |
| `control_service` | `action`: `stop` (refuse new invoices), `start`, `restart` (reconnect relays in-process) | `{ paused, restart_pending }` |
| `backup_database` | none | `{ file, size_bytes, created_at }`, written to `/backups` |
| `wipe_database` | `confirm: "WIPE"`, optional `include_settings`, `force` | `{ deleted, backup }` |
| `get_audit_log` | optional `limit` (1 to 200) | `entries` of `{ at, actor, action, detail }` |
Settings that can be patched: `name`, `relays`, `public_invoicing`, `pow_bits`,
`pow_window_secs`, `min_confirmations`, `default_expiry_secs`, `max_expiry_secs`,
`min_amount_sat`, `max_amount_sat`, `max_open_invoices`, `max_invoices_per_day`,
`rate_global_per_min`, `rate_per_key_per_min`, `rate_requests_per_min`,
`rate_requests_per_key_per_min`, `poll_secs`, `late_grace_secs`, `proxy` and
`sweep` (`enabled`, `mode` = `payjoin` or `coinjoin`, `threshold_sat`,
`max_fee_rate_sat_vb`, `min_anonymity_set`). Unknown fields are refused.
A request sent while the service is reconnecting is not answered; clients should time
out and retry.
## Errors
Errors are JSON-RPC errors with a stable `data.code`. Internal error text never reaches the
caller.
| JSON-RPC code | `data.code` | Meaning |
| --- | --- | --- |
| -32602 | `invalid_params` | Arguments out of range or malformed |
| -32001 | `unauthorized` | Operator-only tool, or public invoicing is off |
| -32002 | `not_found` | No invoice with that id |
| -32003 | `pow_rejected` | Missing or insufficient work, stale, replayed or not addressed to this service |
| -32004 | `rate_limited` | A rate limit was hit; retry later |
| -32005 | `capacity` | Open-invoice or daily cap reached |
| -32006 | `paused` | Invoicing is stopped by an operator |
| -32603 | `internal` | Something failed on the service side |
Arguments that do not match the input schema at all (wrong types, unknown fields) come back
as a tool result with `isError: true` rather than a JSON-RPC error.
---
Source: https://deadhop.run/docs/integrate.html
# Integrate payments into your app
> What every deadhop integration shares (the service, who creates invoices, checking payments, proof of work) and the guide for each client.
A client package and one component package per framework put deadhop into an app you already have. This page covers what every
integration shares. For code, pick your client under [Choose your client](#choose-your-client).
| Package | What it is | Where |
| --- | --- | --- |
| `@deadhop/client` | Framework-agnostic client: connect, create and look up invoices, a headless checkout, QR codes | npm and JSR (the notemine adapter: npm only) |
| `@deadhop/react` | `PayButton`, `InvoiceForm`, `Invoice` and `useCheckout` for React | npm and JSR |
| `@deadhop/solid` | The same for Solid | npm and JSR |
| `@deadhop/svelte` | The same for Svelte 5, and for Svelte 4 at `@deadhop/svelte/svelte4` | npm only (JSR can't host `.svelte` files) |
## What your app talks to
Your app never calls an HTTP API. It sends encrypted messages to a deadhop service over
Nostr relays. Two values identify the service:
| Value | Where it comes from |
| --- | --- |
| `serverPubkey` | The service's public key (hex or `npub`). On the host: `deadhop pubkey`, or the `server.pubkey` file in its data directory. Behind the homelab tooling: `./homelab cvmpay pubkey`. It is also the `serverPubkey` in the dashboard's `config.json`. |
| `relays` | Relays the service listens on (`DEADHOP_RELAYS`, or as changed in the dashboard). Your page needs **at least one** of them. |
The service can be your own (self-hosted) or run by someone else (remote): the code is
the same either way, only these two values change. With a remote service, you trust its
operator to report payments truthfully. You can check its addresses against your own
wallet only if it uses your xpub.
```ts
import { createDeadhop } from '@deadhop/client';
export const deadhop = createDeadhop({
serverPubkey: 'npub1…', // the service's public key
relays: ['wss://relay.example.com'], // shared with the service
});
```
`createDeadhop` connects only when it is first used and keeps one connection, so create
it once per page (or per process) and pass it to every component.
## Two ways to create invoices
### 1. The browser creates them (public invoicing)
The customer's browser creates the invoice itself. A `PayButton` does this in one click.
- On the service: `DEADHOP_PUBLIC_INVOICING=true` (or *Public invoicing* in the
dashboard's Settings).
- The browser signs with a throwaway key made in memory: customers need no Nostr
account and see no extension prompt.
- Each invoice costs the browser a proof of work (`DEADHOP_POW_BITS`, default 20 bits).
The built-in miner took 5.3 s on average for 20 bits in desktop Chrome, and a phone is
slower; it is shown as *Preparing invoice…*. The service also rate-limits public
invoices.
Good for tips, donations, a fixed-price product, or any page without a backend.
Nothing to configure in your app: the service tells each client how much work it wants
(`pow_bits` in `get_info`), and the client mines exactly that before each new invoice.
Operators owe none. To make it faster, see
[Faster proof of work](#faster-proof-of-work-notemine).
### 2. Your backend creates them (operator key)
Your server creates the invoice with an operator key and hands its id to the page. The
page only watches it with ``, which any key may do: the id is the
capability.
- On the service: add the backend's public key to `DEADHOP_ADMINS` (or Settings →
Operators). Public invoicing can stay off.
- No proof of work, and you decide the amount and memo on the server, not the customer.
- **An operator key can also manage the service** (settings, relays, wipe). Keep it on
the server, never in a browser bundle, and use a key made only for this.
See [Backend](./integrate-backend.md) for the code.
## Fulfil orders only after your backend has checked
`onPaid` runs in the customer's browser, and the customer controls the browser. Use it to
update the page, never to release goods. Before you ship, ask the service yourself:
[Backend](./integrate-backend.md#check-before-you-fulfil) shows the check.
- `detected` means the payment was seen, not that it is final. An unconfirmed payment can
still disappear. Wait for `confirmed` (`DEADHOP_MIN_CONFIRMATIONS`).
- An `expired` invoice can still become `confirmed`: the service keeps watching for late
payments (`DEADHOP_LATE_GRACE_SECS`), and the components keep polling.
- Check that `invoice.amount_sat` is what you asked for.
## Choose your client
Every client gets the same three components, with the same props and events:
| Component | Does |
| --- | --- |
| `PayButton` | A button for a fixed `amount` (sats). On click it creates the invoice and shows it: QR code, address, copy button, countdown, then the payment's progress. |
| `InvoiceForm` | Amount and optional note fields. Creates the invoice and shows it, with *New invoice* to start over. |
| `Invoice` | Shows an existing invoice by `id` and follows it until paid. Use it with invoices your backend created. |
| Your app | Import from | Guide |
| --- | --- | --- |
| React 18 or 19 (Next.js too) | `@deadhop/react` | [React](./integrate-react.md) |
| Solid 1.8+ (SolidStart too) | `@deadhop/solid` | [Solid](./integrate-solid.md) |
| Svelte 5 (SvelteKit too) | `@deadhop/svelte` | [Svelte 5](./integrate-svelte5.md) |
| Svelte 4, or Svelte 5 in legacy mode | `@deadhop/svelte/svelte4` | [Svelte 4](./integrate-svelte4.md) |
| Any other framework, or none | `@deadhop/client` | [Plain JavaScript](./integrate-javascript.md) |
| A server (Node, Deno, Bun) | `@deadhop/client` | [Backend](./integrate-backend.md) |
Props every component takes:
| Prop | Type | Meaning |
| --- | --- | --- |
| `client` | `Deadhop` | From `createDeadhop`; required |
| `pollMs` | `number` | How often to check for news (default 5000) |
| `labels` | `Partial` | Replace any text, for example for another language |
| `class` (React: `className`) | `string` | Extra class on the outer element |
| `copy` | `(text) => Promise` | Copies the address (default: the browser clipboard) |
| `onCreated(invoice)` | function | An invoice exists |
| `onDetected(invoice)` | function | The full amount was seen, not yet confirmed |
| `onPaid(invoice)` | function | The full amount is confirmed (verify on your backend) |
| `onError(error)` | function | An `ApiError` with a `code` such as `unauthorized`, `rate_limited`, `timeout` |
`PayButton` also takes `amount`, `memo`, `expirySecs` and its label (`children` in React
and Solid, `label` in Svelte). `InvoiceForm` takes `defaultAmount`, `defaultMemo`,
`showMemo` and `expirySecs`. `Invoice` takes `id`.
## Faster proof of work (notemine)
The built-in miner hashes on the page's main thread, and gives up after 25 seconds.
Mining time varies a lot from one invoice to the next, so at the default 20 bits a slow
phone will sometimes run out of time. [notemine](https://github.com/sandwichfarm/notemine)
mines in WebAssembly across several Web Workers. In headless Chrome on a 16-core
machine, 20 bits took 0.4 s on average with notemine and 5.3 s with the built-in miner.
```sh
npm install @notemine/wrapper @notemine/core rxjs
```
```ts
import { createDeadhop } from '@deadhop/client';
import { notemineMiner } from '@deadhop/client/notemine';
export const deadhop = createDeadhop({
serverPubkey: 'npub1…',
relays: ['wss://relay.example.com'],
miner: notemineMiner(), // pass to every component as usual
});
```
- npm only: `@deadhop/client/notemine` is not on JSR.
- `@notemine/wrapper` is an optional peer dependency: install it only if you use this.
`@notemine/core` and `rxjs` are its own peer dependencies. npm installs them by itself,
some other package managers don't. Without them, the built-in miner quietly takes over.
Its code (about 500 KB) is a separate chunk that loads when the first invoice needs
work, not with the page.
- A page with a Content-Security-Policy must allow notemine's worker and WebAssembly:
`worker-src blob:` and `script-src 'self' 'wasm-unsafe-eval'`.
- Where notemine cannot run (a stricter policy, no Web Workers, server-side), the
built-in miner takes over. Pass `notemineMiner({ fallback: false })` to fail instead.
`workers` sets how many Web Workers it uses (default: one less than the device's
cores, at most 8).
- Whichever miner runs, the client checks the result before it signs anything: the same
request, a `nonce` tag and enough leading zero bits. A broken miner can't make the
client send something the service would refuse.
- `@notemine/wrapper` is MIT, but it includes notemine's WebAssembly core, and
`@notemine/core` is GPL-3.0. Check that this suits your app before you ship it.
To use a different miner, pass any function of type `Miner` (exported from
`@deadhop/client`).
## Styling and page security
- `styles.css` (`@deadhop/react/styles.css`, `@deadhop/solid/styles.css` or
`@deadhop/svelte/styles.css`; the same file in each) is optional. It uses only `deadhop-` classes and custom
properties (`--deadhop-accent`, `--deadhop-radius`, `--deadhop-qr-size`, …) that you can
override. Without it, the components are unstyled semantic HTML. The defaults inherit
your page's font and text colour and use a graphite button; if your page sets
`color-scheme: dark`, the button turns light on its own (browsers with `light-dark()`).
To match your shop instead, set for example `.deadhop { --deadhop-accent: #your-colour; }`.
- No inline styles or injected scripts: the components run under a strict
Content-Security-Policy. Your page needs `connect-src` to allow `wss:` (the relays),
and `img-src data:` only if you add images of your own that need it. With notemine,
also `worker-src blob:` and `'wasm-unsafe-eval'` (see above).
- The QR code is an SVG drawn from the invoice's `bitcoin:` URI. The client checks that
the URI pays exactly the address and amount shown.
- The memo is written by whoever created the invoice. The components show it as plain
text under *Note from the invoice creator*.
- Importing a component never touches `window` or opens a connection. Nothing happens
until it mounts, so server-side rendering works (tested for every framework).
## Installing
```sh
npm install @deadhop/client @deadhop/react # or @deadhop/solid, @deadhop/svelte; plus your framework
npx jsr add @deadhop/client @deadhop/react # JSR: the client, React and Solid
deno add jsr:@deadhop/client
```
`@deadhop/svelte` is only on npm: JSR can't host `.svelte` files. Every framework
package re-exports `createDeadhop`, so the client needs no separate import.
## Checklist for agents and developers
1. Get the service's `serverPubkey` and a relay it listens on.
2. Decide who creates invoices. In the browser: turn on public invoicing. On your
backend: give it an operator key that stays on the server.
3. `createDeadhop({ serverPubkey, relays })` once, and pass it as `client`.
4. Render `PayButton`, `InvoiceForm` or `Invoice` from the subpath for your framework.
5. Allow `wss:` in `connect-src` if your page has a Content-Security-Policy.
Optionally, for faster proof of work on phones, use `notemineMiner()`. With a
Content-Security-Policy, that also needs `worker-src blob:` and `'wasm-unsafe-eval'`.
6. Fulfil an order only after your backend's `getInvoice(id)` returns `confirmed` for the
right amount.
## How it is tested
- **Unit tests:** `@deadhop/client` and every framework's components, at 100% coverage.
- **Svelte 4:** the components also run on the real Svelte 4 runtime.
- **Server-side rendering:** every framework renders to a string.
- **Real stack:** on regtest, the built client and each framework's `PayButton` (in
headless Chrome, under a strict CSP) pay real invoices through a real relay and service.
So does a page using notemine, once with a policy that allows it and once with the
strict policy, where the built-in miner takes over.
- **Packaging:** `just packages` packs all four packages, installs them into fresh React,
Solid, Svelte 5 and Svelte 4 projects, and builds and type-checks each one. It also
checks tree shaking (notemine stays out of apps that don't use it, and loads lazily in
apps that do), then runs publint, Are the Types Wrong and a JSR dry run.
---
Source: https://deadhop.run/docs/integrate-react.html
# React
> Add deadhop pay buttons, invoice forms and invoices to a React 18 or 19 app (Next.js App Router too), or build your own UI with the useCheckout hook.
React 18 and 19 are supported (tested with 19). Read
[Integrate payments into your app](./integrate.md) first: it explains the service values,
who creates invoices, and why `onPaid` is not proof of payment.
## Install
```sh
npm install @deadhop/client @deadhop/react react react-dom
```
## Create the client once
```ts
// src/deadhop.ts
import { createDeadhop } from '@deadhop/react'; // same as '@deadhop/client'
export const deadhop = createDeadhop({
serverPubkey: 'npub1…', // the service's public key
relays: ['wss://relay.example.com'], // a relay the service listens on
});
```
`createDeadhop` connects on first use and keeps one connection. Create it at module level,
not inside a component, so every render and component shares it.
## A pay button
```tsx
import { PayButton } from '@deadhop/react';
import '@deadhop/react/styles.css';
import { deadhop } from './deadhop';
export function Tip() {
return (
console.log('paid', inv.id)}>
Tip 5,000 sats
);
}
```
The button text is `children`; without it the button reads *Pay 5,000 sats*. Needs
[public invoicing](./integrate.md#_1-the-browser-creates-them-public-invoicing) on the
service.
## An invoice form
```tsx
import { InvoiceForm } from '@deadhop/react';
saveOrder(inv.id)} />
```
## An invoice your backend created
```tsx
import { Invoice } from '@deadhop/react';
export function Checkout({ invoiceId }: { invoiceId: string }) {
return router.refresh()} />;
}
```
Your server creates the invoice with an operator key (see [Backend](./integrate-backend.md))
and sends the page its id. The page only watches it, so public invoicing can stay off.
## Your own markup: `useCheckout`
```tsx
import { useCheckout, InvoiceCard } from '@deadhop/react';
import { LABELS } from '@deadhop/client';
export function Buy() {
const [state, checkout] = useCheckout(deadhop, { onPaid: (inv) => console.log(inv.id) });
if (state.phase === 'idle') {
return ;
}
return ;
}
```
`state.phase` is one of `idle`, `creating`, `loading`, `pending`, `detected`, `confirmed`,
`expired` or `error`. `InvoiceCard` draws any state; replace it with your own markup if
you like, using `invoiceView(state.invoice, state.now)` from `@deadhop/client` for the
labels and the QR path. Event callbacks always see the latest props.
## Next.js and server rendering
- The built files start with `'use client'`, so you can import the components straight
into App Router pages.
- Importing a component never touches `window` or opens a connection; it renders to
HTML on the server and connects only after it mounts.
- Create invoices on the server with `@deadhop/client` in a route handler or server
action, never with an operator key in client code (see [Backend](./integrate-backend.md)).
## Language and styling
- `labels` replaces any text, for example for another language:
```tsx
`${sats} sats zahlen`, copy: 'Adresse kopieren' }} />
```
- `className` adds a class to the outer element. The stylesheet is optional; see
[Styling and page security](./integrate.md#styling-and-page-security).
- For faster proof of work on phones, pass `miner: notemineMiner()` to `createDeadhop`
(see [Faster proof of work](./integrate.md#faster-proof-of-work-notemine)).
---
Source: https://deadhop.run/docs/integrate-solid.html
# Solid
> Add deadhop pay buttons, invoice forms and invoices to a Solid 1.8+ app (SolidStart too), or build your own UI with the useCheckout primitive.
Solid 1.8 and later 1.x are supported (tested with 1.9); Solid 2 is not supported yet.
Read [Integrate payments into your app](./integrate.md) first: it explains the service
values, who creates invoices, and why `onPaid` is not proof of payment.
## Install
```sh
npm install @deadhop/client @deadhop/solid solid-js
```
## Create the client once
```ts
// src/deadhop.ts
import { createDeadhop } from '@deadhop/solid'; // same as '@deadhop/client'
export const deadhop = createDeadhop({
serverPubkey: 'npub1…',
relays: ['wss://relay.example.com'],
});
```
## A pay button
```tsx
import { PayButton } from '@deadhop/solid'
import '@deadhop/solid/styles.css';
import { deadhop } from './deadhop';
export const Tip = () => (
console.log('paid', inv.id)}>
Tip 5,000 sats
);
```
The button text is `children`; without it the button reads *Pay 5,000 sats*. Needs
[public invoicing](./integrate.md#_1-the-browser-creates-them-public-invoicing) on the
service.
## An invoice form
```tsx
import { InvoiceForm } from '@deadhop/solid';
export const Shop = () => ;
```
## An invoice your backend created
```tsx
import { Invoice } from '@deadhop/solid';
export const Checkout = (props: { invoiceId: string }) => ;
```
See [Backend](./integrate-backend.md) for creating the invoice on your server.
## Your own markup: `useCheckout`
```tsx
import { Show } from 'solid-js';
import { useCheckout, InvoiceCard } from '@deadhop/solid';
import { LABELS } from '@deadhop/client';
export function Buy() {
const [state, checkout] = useCheckout(deadhop, { onPaid: (inv) => console.log(inv.id) });
return (
checkout.create({ amount_sat: 5000 })}>Buy}>
);
}
```
`state` is an accessor. The checkout stops polling when the owning component is
disposed. To keep callbacks current, pass the component's `props` object (or getters) as
the options.
## SolidStart and server rendering
The package ships a compiled build and, under the `solid` export condition, JSX that
SolidStart and other SSR setups compile themselves. Rendering on the server never opens
a connection.
## Language and styling
`labels` replaces any text, `class` adds a class to the outer element, and the stylesheet
is optional; see [Styling and page security](./integrate.md#styling-and-page-security).
For faster proof of work on phones, see
[Faster proof of work](./integrate.md#faster-proof-of-work-notemine).
---
Source: https://deadhop.run/docs/integrate-svelte5.html
# Svelte 5
> Add deadhop pay buttons, invoice forms and invoices to a Svelte 5 or SvelteKit app, or build your own UI with useCheckout.
These components use runes and need Svelte 5. For Svelte 4, or Svelte 5 in legacy mode,
use [Svelte 4](./integrate-svelte4.md). Read
[Integrate payments into your app](./integrate.md) first: it explains the service values,
who creates invoices, and why `onPaid` is not proof of payment.
## Install
```sh
npm install @deadhop/client @deadhop/svelte svelte
```
npm only: JSR can't host `.svelte` files.
## Create the client once
```ts
// src/lib/deadhop.ts
import { createDeadhop } from '@deadhop/svelte'; // same as '@deadhop/client'
export const deadhop = createDeadhop({
serverPubkey: 'npub1…',
relays: ['wss://relay.example.com'],
});
```
## A pay button
```svelte
console.log('paid', inv.id)} />
```
Events are callback props (`onPaid`), as usual in Svelte 5. Needs
[public invoicing](./integrate.md#_1-the-browser-creates-them-public-invoicing) on the
service.
## An invoice form
```svelte
```
## An invoice your backend created
```svelte
invalidateAll()} />
```
Create the invoice in `+page.server.ts` with an operator key; see
[Backend](./integrate-backend.md).
## Your own markup: `useCheckout`
```svelte
{#if buy.state.phase === 'idle'}
{:else}
{/if}
```
`buy.state` is reactive. Call `useCheckout` during component setup (or inside
`$effect.root`); the checkout stops when the component is destroyed. `events` is a
getter, so callbacks that depend on props stay current.
## SvelteKit and server rendering
Importing a component never touches `window` or opens a connection: pages render on the
server and connect only in the browser.
## Language and styling
`labels` replaces any text, `class` adds a class to the outer element, and the stylesheet
is optional; see [Styling and page security](./integrate.md#styling-and-page-security).
For faster proof of work on phones, see
[Faster proof of work](./integrate.md#faster-proof-of-work-notemine).
---
Source: https://deadhop.run/docs/integrate-svelte4.html
# Svelte 4
> Add deadhop pay buttons, invoice forms and invoices to a Svelte 4 app (or Svelte 5 in legacy mode), or build your own UI with the checkout store.
These components use Svelte 4 syntax, so they also run under Svelte 5 in legacy mode.
They are tested on the real Svelte 4 runtime. Read
[Integrate payments into your app](./integrate.md) first: it explains the service values,
who creates invoices, and why `onPaid` is not proof of payment.
## Install
```sh
npm install @deadhop/client @deadhop/svelte svelte@4
```
npm only: JSR can't host `.svelte` files.
## Create the client once
```js
// src/lib/deadhop.js
import { createDeadhop } from '@deadhop/svelte/svelte4'; // same as '@deadhop/client'
export const deadhop = createDeadhop({
serverPubkey: 'npub1…',
relays: ['wss://relay.example.com'],
});
```
## A pay button
```svelte
console.log('paid', inv.id)} />
```
Events are callback props (`onPaid`, `onDetected`, …), not `on:` events. Needs
[public invoicing](./integrate.md#_1-the-browser-creates-them-public-invoicing) on the
service.
## An invoice form
```svelte
```
## An invoice your backend created
```svelte
```
See [Backend](./integrate-backend.md) for creating the invoice on your server.
## Your own markup: the checkout store
```svelte
{#if $checkout.phase === 'idle'}
{:else}
{/if}
```
A checkout follows the Svelte store contract, so `$checkout` works directly. Destroy it
when the component goes away to stop polling.
## TypeScript
The package ships types for every component. In `