Skip to content

payment-rails.mdx

Latest commit

 

History

History
96 lines (72 loc) · 3.6 KB

payment-rails.mdx

File metadata and controls

96 lines (72 loc) · 3.6 KB
Raw
title Operator Payment Rails
description Operator-only payment adapters for local or self-hosted Froglet nodes.
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 no-clone bootstrap starts with payment_rail=none. Only after the free demo works should an operator ask the Froglet MCP tool to plan a payment rail. It must return a decision checkpoint before any real secrets are entered.

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:

  1. descriptor exposure
  2. payment prepare or reserve
  3. commit or capture
  4. 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.