NWC HTTP API
This is not a wallet and not a new payment protocol. It is an HTTP surface around NIP-47/NWC traffic, useful when an app wants Nostr Wallet Connect payments but prefers request-response endpoints and webhooks over managing relay WebSockets itself.
Start with what it is
NWC HTTP API is best understood as a bridge for developers. It is an Alby-hosted HTTP surface around Nostr Wallet Connect flows, documented in the Alby developer guide and listed in `awesome-nwc` as a way to communicate NWC payment requests without needing WebSockets.
That wording is important. The API is not a wallet. It is not the wallet service that owns the user's Lightning node or account. It is not a replacement for NIP-47. It is a transport helper that lets an application talk to the Nostr relay side of NWC through familiar HTTP requests and webhooks.
A normal NWC app talks to relays over WebSockets. It creates an encrypted request event, publishes it to the relay listed in the user's connection URI, waits for the wallet service to respond, and then decrypts the response. NWC HTTP API wraps parts of that relay work behind endpoints such as publish request, subscribe to events and subscribe to notifications.
For a builder, the value is practical. Your backend, native app or browser client may already be good at HTTP and webhook callbacks, but not at maintaining relay sockets. NWC HTTP API gives that app a more ordinary integration path while keeping the wallet action itself inside the NIP-47 event model.
What NIP-47 still does
The underlying protocol remains NIP-47, also known as Nostr Wallet Connect. NIP-47 defines a client, a user, a wallet service, a connection URI, a relay path, encrypted request and response events, supported wallet methods, error codes and notification events.
The event kinds matter. NIP-47 uses kind 13194 for wallet-service info, kind 23194 for requests, kind 23195 for responses and kind 23197 for notifications, with kind 23196 kept for older notification compatibility. The content of requests, responses and notifications is encrypted. Modern NIP-47 prefers NIP-44 encryption, while NIP-04 remains a legacy compatibility path.
The connection URI matters too. A `nostr+walletconnect://` URI contains the wallet-service pubkey, at least one relay and a client secret. The client uses that secret to sign the request event and derive the keys needed for encrypted communication. The wallet service uses the corresponding client pubkey when replying.
NWC HTTP API does not make those pieces optional. It can publish an event or manage a subscription, but your application still needs to construct a valid NWC request, encrypt it correctly, sign it with the connection secret, target the right wallet pubkey and decrypt the response. HTTP changes the integration ergonomics, not the security model.
The main API surface
The Alby guide presents the NWC HTTP API as a way to fetch NWC info, publish NWC requests and subscribe to events. The guide also says subscriptions and NWC requests can accept webhook URLs so the API can notify your application about new events or response events.
The info endpoint is a simple example. The `GET https://api.getalby.com/nwc/nip47/info` route returns a wallet provider's NWC capabilities if the provider has published them. In NIP-47 terms, that means reading the wallet-service info event, kind 13194, whose content lists supported methods such as `pay_invoice`, `make_invoice`, `lookup_invoice` or `get_balance`.
The publish endpoint is the central payment path. `POST https://api.getalby.com/nwc/nip47` publishes a signed NWC request event and returns the response. The request body includes a relay URL, the wallet provider pubkey and the signed event. If no relay is supplied, the docs say the API uses the default relay `wss://relay.getalby.com/v1`.
The webhook variant, `POST https://api.getalby.com/nwc/nip47/webhook`, is for asynchronous handling. You provide a webhook URL along with the signed event and wallet pubkey. Instead of forcing your app to hold a WebSocket open or poll awkwardly, the API can call your webhook when the response event arrives.
Subscriptions are the second half
NWC is not only one request and one response. Apps often need to watch for events. The Alby docs include `POST https://api.getalby.com/nwc/subscriptions`, which notifies your application about new relay events matching a filter that you provide. The filter is a Nostr event filter, and the callback path is a webhook URL.
There is also a specific NWC notification route. `POST https://api.getalby.com/nwc/nip47/notifications` subscribes to wallet notifications for the connection pubkey from the wallet service. The docs describe this as notifying about kind 23196 events, while the current NIP-47 text says 23197 is the notification kind and 23196 remains for backwards compatibility.
That mismatch is a useful reminder that NWC has lived through protocol evolution. If you build with notifications, test what your wallet service actually emits and what the HTTP API actually forwards. Do not assume a code comment, old docs page or older wallet service has already moved to the latest event kind.
The delete endpoint matters because subscriptions are state. The docs expose `DELETE https://api.getalby.com/nwc/subscriptions/:id` to stop a previously requested subscription. A production app should treat subscription cleanup as part of the integration, not as a nice-to-have, because stale webhooks can keep delivering sensitive or confusing events.
Why HTTP helps
Relay WebSockets are natural for Nostr clients, but not every payment app wants to become a relay client. Many payment integrations live inside backend services, mobile apps, checkout flows, serverless functions, webhook processors or product surfaces that already use HTTP as their native boundary.
NWC HTTP API can make that integration simpler. A backend can create or receive an NWC connection, build a signed request event, send it to an HTTP endpoint and receive a response or webhook. It can use the same operational patterns it already uses for other payment APIs: request logs, retries, callback handlers and service health checks.
That simplification is especially attractive when NWC is one feature inside a larger product. A media app, store, AI service or internal tool may only need to pay an invoice or create an invoice. It does not want to maintain a relay library, reconnect logic and event subscription state just to move one payment.
The tradeoff is dependency. If your NWC path depends on Alby's HTTP bridge, your payment UX also depends on that bridge's availability, latency, rate limits, behavior changes and webhook delivery. HTTP reduces one kind of complexity and adds a third-party API surface you must monitor.
What the API does not hide
The biggest mistake is to treat the HTTP endpoint like a normal custodial payment processor. It is not. You are still using a user-authorized wallet connection. The wallet service still decides which methods the connection may use, which budgets apply, which invoices can be paid and whether a request is authorized.
The API also does not invent wallet capability. If the wallet service does not support `make_invoice`, an HTTP wrapper cannot make it support invoice creation. If the wallet service does not support NIP-44 yet, your encryption negotiation still matters. If a relay drops ephemeral events, the HTTP layer can only work within that network reality.
The API does not remove key custody concerns. Your app still handles an NWC secret or connection-derived client key material. If that secret leaks, an attacker may be able to send requests within the connection's permissions. The safest connection is one with narrow methods, a small budget, a short expiry and an easy revocation path.
The API also does not prove payment intent to the human by itself. If your app pays invoices automatically, the user must understand the permission they granted. A smooth HTTP integration can make payments feel invisible. That is good for UX only when the budget, purpose and controls are clear.
Info events should be checked first
Before publishing a payment request, fetch the wallet-service info event. The NWC HTTP API's info endpoint exists for that reason. A wallet-service info event tells the client which methods are supported and which notification types or encryption modes may be available.
This is not just a documentation nicety. A `pay_invoice` only flow has a different risk and product shape from a connection that can also call `make_invoice`, `lookup_invoice`, `list_transactions` and `get_balance`. Each method expands what the app can ask the wallet service to do or reveal.
NIP-47 also uses the info event to negotiate encryption. The current spec prefers NIP-44 and treats NIP-04 as deprecated compatibility. If the info event does not include an encryption tag, older behavior may be assumed. Apps need to know that before they create the request event, not after a payment fails.
A healthy app should show or at least log the capability check. If a wallet service lacks the method you need, fail before asking the user to connect deeper. If the wallet service supports too many methods for your use case, consider asking the user to create a narrower app connection.
Publishing a request
The publish request path takes a signed event, not a high-level command string. That distinction protects the NIP-47 model. Your app creates the Nostr event, sets kind 23194, adds the wallet-service pubkey as a `p` tag, encrypts the JSON-RPC-like payload and signs the event with the client secret derived from the NWC connection.
The encrypted payload contains the method and parameters. For a payment, that might be `pay_invoice` and a BOLT11 invoice. For invoice creation, it might be `make_invoice` and an amount in millisatoshis, with description or metadata. For transaction lookup, it might include an invoice or payment hash.
The HTTP API can then publish the event and wait for a kind 23195 response, or hand response delivery to a webhook. If the request is successful, the response content decrypts to a result with the matching result type. If it fails, the NIP-47 error object should include a code and a human-readable message.
For your implementation, the important checks are concrete: the event is signed by the right connection key, the `p` tag targets the right wallet pubkey, the payload uses the negotiated encryption mode, the expiration tag is reasonable, the invoice amount is correct and the response event references the request you actually sent.
Webhooks add another trust boundary
Webhooks are convenient because they let your app receive an NWC response or subscription event without holding a relay connection open. They are also a new inbound attack surface. Any public webhook route needs authentication, replay protection, request size limits, logging discipline and clear failure handling.
The Alby docs show webhook support for the NWC request path and for event subscriptions. Your app should not accept a webhook call merely because it arrives on the right URL. It should verify that the event inside the callback is the event you expected, signed by the expected key, encrypted for the expected connection and linked to the original request when applicable.
Replay matters. An old payment response should not be processed as a fresh response if an attacker replays the callback. Store request IDs, response event IDs, timestamps and state transitions. Make processing idempotent so duplicate callbacks do not double-credit a balance or fire a fulfillment action twice.
Webhook reliability also matters. If your endpoint returns errors or times out, what does the API do? Retry? Drop the event? Mark it failed? The docs describe the shape of the endpoints, but your production runbook needs to test callback outage, slow response, malformed event, duplicate event and secret rotation.
Relay selection still matters
The API documentation repeatedly notes that if no relay URL is provided, the default relay is `wss://relay.getalby.com/v1`. That default is useful because it gets developers moving quickly and lines up with Alby's NWC relay documentation.
A default relay is not the same thing as universal delivery. NIP-47 depends on the wallet service listening on the relay or relays named in the connection URI. If your app publishes to a relay the wallet service is not using, the wallet service may never see the request.
For best results, parse and respect the relays in the NWC connection URI. Use the default only when it is actually the intended relay or when the docs for your target wallet service say it is correct. Multi-relay connections should be tested carefully because duplicate responses and partial delivery are possible.
Relays also shape privacy. Even with encrypted content, relays can see event kinds, timestamps, pubkeys, tags and traffic patterns. The HTTP bridge may also see request metadata. Choose relays with the same care you would use for any payment-adjacent messaging path.
Permissions are the real safety layer
NWC connections should be scoped. The NIP-47 text explicitly describes different keys for different applications, revocation and arbitrary constraints such as budgets. That is the safety layer that makes automatic or native in-app payments tolerable.
For an HTTP API integration, scoping becomes even more important. A backend service may store the NWC connection string, send requests without another user confirmation and process payments from scheduled jobs or webhooks. A broad connection in that environment is a standing wallet API key.
Use a dedicated app connection per product surface. If the app only pays invoices, it should not need transaction history or invoice creation. If it only creates invoices for a Lightning Address server, it should not need outgoing payment permission. If the app is experimental, use a tiny budget and a short expiry.
Also design for revocation. The user should know which wallet connection is tied to the app, what it can do and how to disable it. Your app should handle revoked connections gracefully rather than looping failed requests or asking users to paste the same secret into more places.
Where it differs from SDKs
Alby and the wider NWC ecosystem also provide SDK paths. The NWC site shows JavaScript and Rust examples, and Alby's developer guide includes an NWC JS SDK section. Those SDKs are often the better choice when your app can run a normal NWC client directly.
The HTTP API is most useful when you want the relay interaction behind a web endpoint, or when webhooks fit your architecture better than WebSocket subscriptions. It can be a bridge for server-side code, serverless functions, native environments or products whose backend already treats payment events as HTTP callbacks.
The SDK path may give you more direct control over relay behavior, retries, encryption handling and client state. The HTTP path may give you simpler integration and less relay plumbing. Neither path removes the need to understand NIP-47 events and permissions.
A good rule is simple: if your app team is comfortable running an NWC client library and needs control, use an SDK. If your app primarily needs a managed relay-to-HTTP bridge and can accept the dependency, NWC HTTP API may fit. In both cases, test with the exact wallet service and connection permissions you plan to support.
Developer checks before launch
Begin with a test wallet connection. Fetch info. Confirm the wallet pubkey, methods and encryption modes. Publish a harmless request such as `get_info` if permitted. Then test the real method you need, such as `pay_invoice` or `make_invoice`, with the smallest meaningful amount.
Log event IDs, not secrets. Store enough state to connect a request event to a response event, but do not log the NWC URI, client secret, plaintext request payload or decrypted sensitive result. If you need debug logs, redact before they leave local development.
Test failure codes. NIP-47 defines errors such as unauthorized, restricted, quota exceeded, insufficient balance, unsupported encryption, rate limited and internal. Your UI and backend should not flatten those into one vague payment failed message. Each one implies a different user action.
Finally, test cleanup. Create an event subscription, receive a webhook, delete the subscription and confirm no further callbacks arrive. Rotate the NWC connection. Revoke the wallet connection. Let a webhook endpoint fail for a few minutes. These cases reveal whether the integration is stable enough for real users.
User-facing risks
A user may never see NWC HTTP API directly, but they will feel its choices. If a product hides the wallet connection too deeply, users may not understand that an app can request payments from their wallet within the permissions they granted.
That is why the app using the API should explain the connection in plain language. What wallet is connected? What can the app do? Is there a budget? Does each payment require confirmation? Can the app create invoices, inspect balance or list transactions? Where can the user revoke access?
The HTTP bridge also means the app operator depends on a third-party API path. If that API is unavailable, payments may stall even if the user's wallet and relays are otherwise healthy. If the webhook path is misconfigured, a payment may succeed while the app never marks the order, post, stream or account action complete.
For money-facing UX, design for ambiguity. Show pending state. Let users retry safely. Never charge twice because a webhook repeated. Provide a way to reconcile a paid invoice with a missing app action. Small Lightning payments are still real money, and bad state handling burns trust quickly.
Where it belongs in the map
NWC HTTP API belongs in Developer Tools & Libraries because it is a builder surface. It is not a wallet interface for ordinary users and not a standalone payment app. It helps developers connect apps to the NWC protocol with HTTP and webhooks.
It also touches Lightning Backends and Finance & Payment Tools, but those categories would overstate the user-facing product. The API does not settle Lightning payments by itself. It helps an app send signed NWC events to a wallet service that performs or reports the wallet action.
The Nostr relationship is exact. It exists because NWC uses Nostr relays, Nostr event kinds, pubkeys, signatures and encrypted event content for wallet communication. The HTTP API is valuable precisely because it lets products use that Nostr-native payment path from a more conventional integration surface.
That makes it an important page for readers who build, but a confusing page if it is presented as an app. The right mental model is bridge infrastructure: HTTP on one side, NIP-47 events and relays on the other, wallet permissions underneath.
The practical close
NWC HTTP API is useful because it makes Nostr Wallet Connect easier to integrate into products that already think in HTTP requests and webhook callbacks. It lets an app fetch wallet capabilities, publish signed NWC request events, receive responses and subscribe to wallet-related events without directly managing relay WebSockets.
It is also easy to misuse if you forget what remains underneath. The app still holds sensitive NWC connection material. The request still needs to be signed and encrypted correctly. The wallet service still controls authorization. Relays still shape delivery. Webhooks still need verification and replay protection.
Use it when the architecture fits. Keep permissions narrow, fetch info first, respect the connection URI relays, test the exact wallet service, make callback handling idempotent, delete stale subscriptions and keep secrets out of logs.
If those checks are in place, the API can be a practical bridge from ordinary web infrastructure into NWC. If they are skipped, it becomes a smooth way to hide payment risk behind a neat endpoint.
Useful Nostr context
These pages explain the pieces around the HTTP bridge: the underlying protocol, direct SDK paths and relay behavior.
- NIP-47 and Nostr Wallet Connect: Use this when the article mentions NWC secrets, wallet-service permissions or app-to-wallet requests.
- Alby Hub: A practical wallet-service reference point for NWC connections and app permissions.
- Alby JavaScript SDK: The SDK layer behind many Alby browser and app integrations.
- Relays: The network layer that carries Nostr events, including NWC requests and responses.
- nwcjs: A direct browser-code contrast to the HTTP bridge approach.
- NWC Tester (Simple): A quick sanity check for a connection before wiring it into a backend flow.
Sources worth opening
Start with the Alby NWC HTTP API guide and its endpoint pages, then compare NIP-47 itself, the NWC site, Alby's relay documentation and the official NWC docs so the HTTP layer does not get confused with the underlying wallet protocol.
- Alby NWC HTTP API guide
- Alby Fetch NWC Info endpoint
- Alby Publish NWC Request endpoint
- Alby Publish Event endpoint
- Alby Subscribe to Events endpoint
- Alby Subscribe to NWC Notifications endpoint
- Alby Delete Subscriptions endpoint
- Alby NWC HTTP API code example
- Alby guide to Nostr Wallet Connect
- Alby NWC JS SDK guide
- Alby NWC Relay guide
- Nostr Wallet Connect homepage
- Nostr Wallet Connect docs
- NWC references and SDKs
- NWC relay documentation
- NWC best practices
- NIP-47 Nostr Wallet Connect
- NIP-47 raw specification
- NIP-44 encrypted payloads
- NIP-04 legacy encrypted direct messages
- NIP-01 basic protocol flow
- NIP-57 Lightning zaps
- awesome-nwc GitHub repository
- awesome-nwc raw README
- Alby JavaScript SDK repository
- Rust Nostr NWC module
