Usage

Usage

This page walks through the main workflows. Every UI action maps to a REST call documented in API.

1. Add a relay

CLINK communicates over ordinary Nostr relays. The node listener stays subscribed to every enabled relay and answers kind 21001 / 21002 requests.

1. Open the CLINK extension.
2. Go to the Relays tab and click Add relay.
3. Enter a relay URL (wss://relay.damus.io, wss://relay.primal.net, your own nostr-rs-relay, …) and enable it.

The status banner in the index page reflects whether the listener has at least one enabled relay.

2. Offers (receiving payments)

An offer is a noffer1... string. Anyone with it can request an invoice from your wallet over Nostr.

1. Offers tab → New offer.
2. Give it a name. Set an amount in sats for a fixed price, or leave it empty for a spontaneous offer.
3. Create. The row shows the generated noffer1... — share it (QR, copy button) or link to the public checkout page.

A fixed offer also gets a checkout page at /clink/checkout/{offer_id} — a self-contained HTML page where anyone can enter/copy the amount and get a BOLT11 invoice. The offer matches kind 21001 requests, validates the requested amount against the offer price, and returns the invoice encrypted with NIP-44.

3. Debits (letting apps charge you)

A debit pointer is an ndebit1... string. When an app sends a kind 21002 request addressed to it, your wallet settles it — subject to the rules you set.

1. Debits tab → New debit pointer.
2. Optionally set a fixed amount (sats), a budget per period, a frequency (day/week/month), and a rules JSON:

   {
     "allowed_pubkeys": ["<hex pubkey of the app>"],
     "min_msat": 1000,
     "max_msat": 1000000
   }

3. Create and share the ndebit1... string.

What the node does with an incoming request:

• Direct payment (bolt11 present): decodes and validates the invoice, checks the fixed amount / min-max rules, deducts from the period budget (clink.debit_usage), pays with pay_invoice, and replies {"res":"ok","preimage":…}. Budget is rolled back if the payment fails.
• Budget request (frequency present): validates frequency and amount against the pointer and acknowledges with {"res":"ok"}.
• Session k1: if the ndebit1... carries a 32-byte session identifier, the request must echo it and it is single-use (tracked in clink.k1s).

Failures are answered with a GFY payload ({"res":"GFY","code":…,"error":…}).

4. Pay an offer (outgoing)

1. Open CLINK → Pay (/clink/pay).
2. Paste a noffer1... string and hit Parse — the decoded offer (id, relay, pubkey, price type/price) is shown.
3. Enter the amount for spontaneous offers and hit Pay.

The payer sends a kind 21001 request signed by a fresh ephemeral keypair (per the CLINK SDK recommendation), waits for the encrypted invoice response, pays it with your LNbits wallet, and reports the payment hash and preimage.

5. Plans & subscriptions (recurring charges)

A plan is a recurring price. A subscription links a plan to a payer's ndebit1... pointer.

1. Open CLINK → Subscriptions (/clink/subscriptions).
2. Plans tab → New plan: name, amount (sats), frequency number + unit (day, week, month).
3. Subscriptions tab → New subscription: pick the plan and paste the payer's ndebit1... pointer (their wallet node's static debit pointer, e.g. from ShockWallet / Lightning.Pub).

How billing works:

• When a subscription is created, the first period end is now + frequency.
• A permanent poller (clink_subscriptions, every 60 s) finds active subscriptions whose period has ended.
• For each, the node creates a BOLT11 invoice on your wallet for the plan amount, sends a kind 21002 direct-payment request to the payer's node (via the payer's relay + your enabled relays), and waits for the encrypted response.
• On {"res":"ok"} the period advances by one frequency and the attempt counter resets.
• On GFY or timeout the attempt counter increments; after 3 failed attempts the subscription is cancelled. Manual retry is available from the UI (Bill now) or the API.

Subscription states: active → (renewal) → active or, after max attempts, cancelled. You can also paused/cancelled/active a subscription from the UI; resuming resets the attempt counter.

Note: subscriptions and debit settlement require a real Lightning backend (see Installation).

Disabling / deleting

• Toggle any offer, debit pointer, plan, or relay on/off with its switch.
• Delete removes the record. Deleting a relay just stops listening on it; deleting an offer makes its checkout page and requests fail.