Give your app a wallet connection,
not the wallet itself.

Build a paid service

Let a user-authorised wallet pay for an API call, a tool, compute or content without putting wallet keys on your server. This is the shape used by the 402‑mcp payment bridge.

Give an agent spending power

An agent can discover capabilities and request a payment through a bounded connection. Approval, budgets and business policy stay with the application and the wallet, never inside this protocol client.

Keep the boundary small

You get NIP‑47 transport, NIP‑44 v2 encryption and authenticated responses. You do not get custody, invoice verification or settlement claims. That narrow boundary is the point.

The relay

Subscription filters are performance hints, not authentication. Every response is shape-checked, signature-verified and matched to the live request before anything is decrypted. A valid wallet event that does not reference the active request is treated as a possible replay and ignored, rather than allowed to fail the request.

Legacy encryption

NIP‑04 is refused, not merely deprecated. The client requires the wallet to advertise nip44_v2 in a signed capability event before it will send anything at all, and it checks the wallet author, request reference, client recipient and result method before trusting a result.

Silence

Once publication begins, timeout, abort, close and publish failure are ambiguous outcomes. A relay can store an event without returning a usable acknowledgement. The library says so, the types say so, and the docs say so, because a blind retry can pay twice.

A timeout is not a refund. Reconcile against the original invoice before you retry anything — the wallet is authoritative for whether it attempted a payment, and the absence of an answer tells you nothing about what it did.

import { NwcClient } from '@forgesworn/nwc-kit'
import { tryDecodeBolt11, verifyPreimage } from 'farrier-kit'

const client = new NwcClient(connectionUri)

try {
  const caps = await client.connect()
  if (!caps.methods.includes('pay_invoice')) {
    throw new Error('This connection cannot pay')
  }

  const decoded = tryDecodeBolt11(invoice)
  if (!decoded || decoded.amountMsats === null) {
    throw new Error('Refusing an amountless invoice')
  }

  const result = await client.payInvoice({ invoice })

  if (!verifyPreimage(result.preimage, decoded.paymentHashHex)) {
    throw new Error('Response does not settle this invoice')
  }
} finally {
  client.close()
}

connect()

Signed capability discovery. Nothing is sent until the wallet has advertised nip44_v2 in an event it signed itself.

payInvoice()

Returns a validated preimage. Validated means well-formed and authenticated — not that the payment settled. That check is yours.

makeInvoice()

Amount in milli-satoshis, like every other amount, balance and fee field on this page. Convert sats explicitly at the application boundary and reject ambiguous amounts before making a request.

lookupInvoice()

By payment hash or by invoice. The only honest way to answer “did that actually settle?” after an ambiguous outcome.

getBalance(), getInfo()

Milli-satoshis, and wallet metadata.

close()

Cancels outstanding work and zeroises key material.

inspectNwcConnection()

Reads a connection URI — relays, wallet pubkey, budget hints — without exposing the secret.

Transaction history is draft extension 05 and lives at @forgesworn/nwc-kit/extensions/05. It always sends an explicit page limit, capped at 20, because a wallet asked for no particular page size applies a larger default of its own — Alby Hub's is 50.

The boundary stays put. nwc-kit does not implement LNURLcash, store bearer notes or verify invoices. The worked recipe uses farrier-kit for the money checks and has been run against a live experimental mint. LNURLcash is still a draft, so keep the connection and the note value small while testing.

Explore LNURLcash → Read the recipe