---
title: Operator Payment Rails
description: Operator-only payment adapters for local or self-hosted Froglet nodes.
---

<div class="learn-hero compact">
  <div>
    <div class="learn-pill">Operator-only adapters</div>
    <p class="learn-lead">End users should not configure Lightning nodes, Stripe secrets, or x402 wallets just to use Froglet.</p>
    <p class="learn-sublead">The hosted trial at <code>try.froglet.dev</code> is free-only: <code>demo.add</code> 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.</p>
  </div>
</div>

## 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:

```bash
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

- [Lightning](/learn/payment-lightning/)
- [Stripe](/learn/payment-stripe/)
- [x402](/learn/payment-x402/)

## 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.