Operator Payment Rails

Operator-only adapters

End users should not configure Lightning nodes, Stripe secrets, or x402 wallets just to use Froglet.

The hosted trial at try.froglet.dev is free-only: demo.add is the canonical proof. These adapters are for local/self-hosted operators, paid-staging, and future managed infrastructure where Froglet hides the payment backend from ordinary buyers.

Customer vs operator setup

Customer path:

Hosted trial: no payment account, no wallet, no node credentials.
Future hosted paid path: card checkout or a hosted invoice surface; the buyer does not run LND or manage channel liquidity.
Self-hosted free path: payment_rail=none.

Operator path:

The recommended no-clone default is payment_rail=none. When an operator explicitly selects a paid rail, the generated bootstrap command carries that selection after the pipe, verifies the rail, and persists its private env file before activating either launchd/systemd or the Docker fallback. A decision checkpoint is still required before any real secrets are entered, and the free demo remains the safest first proof.

Use these rail names in MCP:

none
lightning-lnd-rest
stripe-test
stripe-live
x402

stripe-live requires a fresh human approval and a tiny live payment/refund proof before public copy can claim live fiat. lightning-lnd-rest is advanced operator infrastructure: it requires the operator’s LND REST URL, macaroon, TLS cert, backups, and channel liquidity. Do not present it as normal customer onboarding.

Source helper

If you are in a source checkout or operator runbook, the repo-local helper can write env snippets and run probes:

cd froglet && ./scripts/setup-payment.sh lightning
cd froglet && ./scripts/setup-payment.sh stripe
cd froglet && ./scripts/setup-payment.sh x402

Each command:

writes a validated env snippet
prints the exact secrets or inputs still required
runs a verification probe for that rail

Choosing a rail

Rail	Best first use	Verification path
Lightning	operator-controlled Bitcoin settlement, not ordinary buyer onboarding	mock mode locally, optional `lnd_rest` probe
Stripe	operator card-flow development and paid-staging proof	`GET /v1/account` with a test secret key and `livemode=false`
x402	operator-controlled USDC-style machine-to-machine endpoints	local Base-address/network validation plus facilitator `/verify` reachability

The current public Stripe and x402 adapters reuse the configured numeric service price directly on the local runtime path. They do not perform FX conversion from sats into backend-native fiat or token units.

Operator guides

Verification lifecycle

Across all three local/self-hosted adapters, the local /v1/node/* runtime helpers use the same stages:

descriptor exposure
payment prepare or reserve
commit or capture
cancellation or release

Only Lightning currently extends that lifecycle into standardized quote/deal settlement terms and invoice-bundle artifacts. The rail-specific docs below explain how each backend maps the local runtime stages to its own provider.

Priced async jobs are not a paid-rail proof today. Use the synchronous /v1/node/events/query or /v1/node/execute/wasm helpers for Stripe/x402 token-settled work, and use the signed quote/deal flow for Lightning-priced work, until durable async payment reservations are implemented.