From 55dba5136c35e779669bdde19da545b1da994e59 Mon Sep 17 00:00:00 2001 From: 9qeklajc Date: Fri, 31 Jul 2026 02:24:28 +0200 Subject: [PATCH] docs: document PPQ auto top-up --- docs/provider/configuration.md | 62 ++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/docs/provider/configuration.md b/docs/provider/configuration.md index 33efabb8..4f83e672 100644 --- a/docs/provider/configuration.md +++ b/docs/provider/configuration.md @@ -48,6 +48,68 @@ Connect to your AI provider(s): | **Upstream URL** | API endpoint (e.g., `https://api.openai.com/v1`) | | **API Key** | Your provider's API key | +### PPQ Auto Top-up + +PPQ providers can automatically purchase more credits when their USD balance +falls below a configured threshold. Configure this per provider in the Admin +Dashboard by editing a **PPQ.AI** provider and opening **PPQ Auto Top-up**. +There are no environment variables for this feature. + +#### Requirements + +Before enabling auto top-up, make sure that: + +- the PPQ provider has a valid API key; +- at least one trusted Cashu mint is configured; +- the node wallet has enough **node-owned** funds at one mint to pay the + Lightning invoice; client balances are never used; and +- the node has a current BTC/USD price for validating the invoice amount. + +| Setting | Description | +| ------- | ----------- | +| **Enable Auto Top-up** | Enables automatic PPQ credit purchases for this provider. | +| **When credits are below (USD)** | Starts a top-up when the reported PPQ balance is below this positive USD value. | +| **Purchase this amount (USD)** | Amount of PPQ credit to buy per top-up. Must be a whole number from **1 to 500 USD**. | + +For example, a threshold of `5` and purchase amount of `20` buys 20 USD of +credit when the PPQ balance drops below 5 USD. + +#### How it works + +The worker checks eligible providers approximately once per minute. When the +balance is below the threshold, it: + +1. verifies the node has enough owner funds before creating an invoice; +2. requests a USD-denominated Lightning top-up invoice from PPQ; +3. rejects expired, mismatched, or unexpectedly expensive invoices (more than + 10% above the local BTC/USD estimate); +4. pays from the configured Cashu mint with sufficient owner funds; and +5. waits for PPQ to confirm that the credit settled. + +Only one attempt can be active for a provider. An attempt that was active at +the start of a cycle suppresses another top-up for that entire cycle, even if +PPQ reports it settled immediately. This prevents a temporarily stale PPQ +balance from causing a duplicate purchase. + +Completed PPQ payments appear in the dashboard transaction history with source +`ppq_auto_topup`. The payment record is separate from the internal claim used +to prevent concurrent attempts. + +#### Payment recovery + +If the Cashu mint paid the invoice but PPQ settlement cannot be confirmed, the +provider card shows **Auto top-up needs review**. A payment still owned by a +running worker is shown as **Payment in progress** and cannot be released. + +Before choosing **Release top-up**, manually verify both PPQ and the Cashu mint. +Release the claim only when the previous Lightning payment is definitively +unable to settle. Releasing an ambiguous payment allows the next cycle to try +again and can therefore cause a duplicate top-up. + +Disabling auto top-up prevents new purchases, but the node continues to +reconcile an already active payment until it reaches a safe terminal state or +requires operator review. + ### Node Identity How your node appears to clients: