---
title: "Register or replace the org's receive-only Lightning receiver for priced routes"
method: POST
path: "/orgs/v1/{org_id}/lightning-receiver"
tags: ["Org"]
---

# Register or replace the org's receive-only Lightning receiver for priced routes

`POST /orgs/v1/{org_id}/lightning-receiver`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/orgs/v1/{org_id}/lightning-receiver`
- Auth: one of:
  - HTTP bearer
  - API key in header `SIGN-IN-WITH-X`
  - API key in header `x-admin-key`

Admin/owner-only, with step-up or fresh SIWX. Takes a Nostr Wallet Connect pairing (nwc_uri) on a node the organization controls. Before storing anything the gateway probes it: get_info must answer with a node public key on mainnet or testnet, make_invoice must be permitted, a pairing that permits pay_invoice (or any other spending method) is refused, and a one-satoshi test invoice must commit to the description hash the gateway supplies and be signed by the reported node. A failed check answers 422 LIGHTNING_RECEIVER_PROBE_FAILED with details.check naming it (get_info, can_spend, make_invoice, description_hash, signer, network). The pairing is stored encrypted, returned by no read, and used only to mint invoices for routes priced on lightning / lightning-testnet; sats settle on the organization's own node and Run402 never holds a spending credential or a preimage. Replacing a receiver rotates receiver_id. Audited; the organization is notified.

## Path parameters

- `org_id` string, uuid, required

## Request body

- LightningReceiverSetRequest
  - `nwc_uri` string, required: A nostr+walletconnect:// pairing on a node the organization controls, permitting get_info and make_invoice and no spending method. Never returned by any read.

## Response `200`

Receiver replaced (a new receiver_id).

- LightningReceiver
  - `org_id` string, uuid, required
  - `receiver_id` string, uuid, required: Rotates on every replacement; each issued invoice names the receiver that minted it.
  - `node_pubkey` string, required: The node's compressed public key (hex): the payTo of every Lightning entry and the key every invoice is signed with.
  - `network` string, required: The lnbtc network id the receiver serves: lnbtc:000000000019d6689c085ae165831e93 (mainnet) or lnbtc:000000000933ea01ad0ee984209779ba (testnet).
  - `methods` string[], required: The NIP-47 methods the pairing permits, as probed.
  - `probed_at` string, date-time, required
  - `last_probe_status` 'ok' | 'failing', required: failing after a mint through the receiver failed; ok again after the next successful mint.
  - `last_error` string, nullable, required
  - `custody` 'organization', required: The sats land on the organization's own node; Run402 holds only a receive-only pairing.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `201`: Receiver registered.
- `400`: nwc_uri missing, not a nostr+walletconnect:// pairing URI, or an unsupported field.
- `403`: Caller is not an org admin/owner, lacks fresh auth, or is a grant key.
- `422`: LIGHTNING_RECEIVER_PROBE_FAILED: the pairing failed a probe check named in details.check.

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)