Node-backed Setup
Node-backed connects a customer-controlled Lightning node and reserve to the shared Voltage Payments API. Use this path when your organization needs direct ownership of node credentials, approved recovery material, treasury operations, and Lightning liquidity.
What you own
Your organization owns node credentials, approved backup and recovery procedures, API credentials and macaroons, treasury policy, liquidity targets, monitoring, and internal production approvals.
Voltage provides the hosted infrastructure and integration support defined for your account. Confirm the exact operating and support boundary during onboarding; do not assume Voltage has access to move funds or administer the node.
Before kickoff
- Assign named owners for the node, Payments integration, credentials, treasury, liquidity, incident response, and production approval.
- Confirm the intended Bitcoin network and Payments environment for each implementation stage.
- Define how node credentials, approved backup and recovery material, macaroons, API keys, and TLS material will be generated, stored, rotated, and accessed.
- Agree on funding, liquidity, reconciliation, and escalation procedures before customer funds are introduced.
Phase 1: Qualify the operating model
Confirm that Node-backed is the correct model for the required custody, control, and operational responsibilities.
Document which actions are customer-operated and which actions, if any, Voltage is authorized to perform under the current support agreement.
Phase 2: Build in staging
Use the Staging EnvironmentStaging Environment to validate the shared Payments API workflow before production.
For a Node-backed Bitcoin implementation, choose Mutinynet Bitcoin when creating the Development wallet. Mutinynet USD is reserved for USD line-of-credit testing, while Voltage Cash is the experimental stablecoin test wallet and is not currently live.
Test wallet creation, authentication, payment requests, sending, receiving, payment history and status reads, failure handling, and Payments API webhooks. Keep credentials environment-scoped and separate staging data from production data.
Phase 3: Provision the Lightning node
Use the current in-product node provisioning workflow for your team. Product labels and navigation can change, so follow the interface presented to your account instead of relying on historical screenshots or dashboard paths.
Create and securely store the approved node credentials and recovery material. Verify that the node is available and synchronized before associating it with a Payments wallet.
Phase 4: Connect Payments to the node
Use the current wallet creation or wallet configuration flow to associate the approved team node with the intended Payments environment.
Verify the selected network, environment, node, and wallet before completing the association. Do not reuse production credentials in staging.
Phase 5: Configure access
Use Access ModelAccess Model, Node SecurityNode Security, Payments AccessPayments Access, and MacaroonsMacaroons to design least-privilege access.
Create only the credentials required by each application or operator. Store macaroons, API keys, TLS material, and node connection details as secrets. Rotate or revoke access when ownership changes or exposure is suspected.
Do not share unrestricted credentials by email, chat, tickets, or documentation. A support credential is required only when explicitly agreed for a defined support workflow.
Phase 6: Validate the payment lifecycle
Exercise the same application paths that will run in production. Confirm wallet policy, quote handling, payment requests, sends, receives, payment history, status transitions, idempotency, webhook verification, reconciliation, and retry behavior.
WebhooksWebhooks are the supported event path for Payments integrations.
Phase 7: Fund and operate liquidity
Define the initial funding source, approved destination wallets, minimum and maximum operating balances, channel and liquidity targets, approval thresholds, and emergency withdrawal process. Use Liquidity ManagementLiquidity Management for the operating model.
Reconcile Payments API activity with direct node and treasury records. Alert on balance drift, failed payments, channel health, stale data, and credential or node availability problems.
Tools and IntegrationsTools and Integrations are optional node interfaces. They are not required steps in the Node-backed onboarding flow.
Phase 8: Production readiness
Complete a production review covering ownership, backups and recovery, credential isolation, node health, funding, liquidity, monitoring, webhook delivery, reconciliation, incident response, and rollback procedures.
Run a controlled send and receive test with production credentials and verify the result through both Payments and node records before increasing limits or volume.
Responsibility boundary
Customer responsibilities
Operate credentials and recovery material, approve treasury movements, fund the node, define liquidity policy, monitor application and node behavior, reconcile records, and maintain incident contacts.
Voltage responsibilities
Provide the contracted hosted infrastructure and Payments integration surface, maintain the documented product interfaces, and perform only the support actions authorized for the account.
Continue
- Node-backedNode-backed for the Payments journey and ownership boundary.
- Node-backed InfrastructureNode-backed Infrastructure for node lifecycle, direct LND access, liquidity, Bitcoin Core, and tools.
- Developer GuideDeveloper Guide for wallets, payment requests, sends, receives, payment history, and webhooks.
- ConfigurationConfiguration, RESTREST, GRPCGRPC, and ResourcesResources for supported direct-node connection options.
- Tools and IntegrationsTools and Integrations for optional node interfaces.
- WebhooksWebhooks for Payments event delivery.