LP Ranger Help and User Manual

Contents
  1. Getting Started & How to Use
  2. Bookmarking Positions
  3. Fund Tracking
  4. Automatic Residual Cleanup
  5. Range Width
  6. Volatility Doubling
  7. Gas Cost Protection
  8. Closed Positions
  9. Telegram Notifications
  10. Troubleshooting
  11. Details
  12. Checking for Updates
  13. Supported Liquidity Pool Managers
  14. Supported Blockchains

Getting Started & How to Use

  1. First, read the README’s Overview section, and then, read the README’s Usage section.
  2. You must read and understand the Disclaimer and the Disclosure linked at the Disclaimer, before proceeding.
  3. If you are running on a Raspberry Pi 5 or similar device that defaults to a very low-resolution on the screen, consider setting the “Zoom” on your web browser to about 80%, to ease use of the app.
  4. On first load of the app, wait for the initial synchronization of the app with the blockchain data to complete. This initial sync handles the default selected liquidity position, if any. It will be repeated for each brand-new liquidity pool that you have a position on. This is a read-only operation but can take a while. Don’t worry though: The results are cached so that, normally, you won’t have to wait again. While with a valid Moralis API key that is not at its quota limit, it will be fastest, this one-time process can take up to two hours to complete. Watch for the Sync Status badge near top-right on the app to read “Synced”. At that time, the blur on the app details section will clear.
  5. Next, consider which Liquidity Positions you want to manage, by clicking on the “Positions” button near center top on the app if in three column-view, or at the left if in single-column view. Alternatively, you can just manage the currently-loaded position. Before clicking the “Manage” button on any position, check that all settings on the app are appropriate for the gas cost on the blockchain you are using, and for the level of slippage that you will require.
  6. First, check the amount on the “Threshold” setting for Auto-compound. If gas costs are high, you will want this number to be large enough that gas costs are a small fraction of it. Next, scroll down to ensure that the settings under “Bot Configuration” are to your liking. For example, be sure to set a slippage percent that is appropriate for that pair (otherwise, the swaps to rebalance your LP position will fail due to insufficient slippage, or will be too costly if you set slippage too high). Also, if your pair requires high slippage, then you will want to control the frequency of rebalancing for that pair. There are several settings for this and the easiest is the per-day limit. For high-slippage, you might want to restrict rebalances to one per day, to control loss from slippage. Carefully read each circle-i tooltip for all the settings so that you understand them all. When you are ready, click the “Manage” button. Each managed position runs its own independent rebalance loop.
  7. Wait for the “Sync” label near top right to finish (“Synced”). Syncing usually just takes a few minutes, but for a very long chain of liquidity positions in a given pool, it can take longer: Almost never more than 30 minutes, but possibly more. Don’t worry though: The results are cached so that, normally, you won’t have to wait again.
  8. When the price moves out of the configured range, the bot automatically rebalances by draining the old position and minting a new one centered on the current price. A rebalance lock ensures only one position transacts at a time (same wallet = same nonce).
  9. Each browser tab shows one position via URL. Open multiple tabs to monitor multiple pools simultaneously. If running on a lighter-weight machine such as a Raspberry Pi 5 or similar, it’s best to keep it to just one open web browser tab.
  10. Historical rebalance events are scanned up to 5 years back and used to calculate lifetime P&L.
  11. The $usd value of the total lifetime deposit is automatically detected. In case of a problem with that, a dialog pops up to notify the user of the opportunity to enter it manually instead at top left in the app under “Total Lifetime Deposit”. Manual entries there always override any auto-detected value.
  12. Wallet Residuals: Residuals are tokens that you intended to put into a liquidity position but that did not fit the chosen price range. They happen in two places: (1) when you first mint the position on the 9mm Pro dApp — the dApp deposits only what the range can accept at the current price and leaves the rest in your wallet on purpose; and (2) when the bot rebalances into a narrow new range and a little is left over. In both cases LP Ranger recognizes these wallet tokens as residuals for that specific pool, tracked separately from the on-chain LP value. On the very next rebalance the residuals are swept into the freshly minted position and, at that point, roll into your lifetime deposit for the pool. If you would rather not wait, click “Rebalance Now”, widen the range by at least one percent in the dialog, and click “OK” — the residuals will be folded in immediately. If multiple positions share a token, the wallet balance is split pro-rata based on each position’s in-range token amount.

Bookmarking Positions

The address bar updates as you switch positions. The URL looks like /pulsechain/<wallet>/<nft-contract>/<tokenId>. Add it to your browser bookmarks (or drag the address bar icon to the bookmarks bar) to jump straight to any position later. Opening a bookmark loads LP Ranger and activates that exact position as soon as the app is ready. Each bookmark is self-contained, so you can keep one per pool or one per NFT and switch between them with a single click. Bookmarks survive app restarts because they only reference on-chain identifiers — nothing in the URL depends on the server’s current managed-positions list.

Fund Tracking

When a position is rebalanced, all collected tokens (principal + earned fees) are recycled into the new position. Any remainder that doesn't fit the new range stays in your wallet and is automatically counted toward your P&L at current market prices, capped to your actual wallet balance. If you withdraw or sell tokens yourself, use Edit Realized Gains to account for them so your P&L stays accurate.

Automatic Residual Cleanup

After every successful rebalance, LP Ranger waits 10 minutes and then checks whether the wallet still holds a meaningful residual share of the position’s tokens. If the residual is still more than 5% of the combined LP + residual value for that pool, the bot fires one additional rebalance to sweep the leftover tokens into the position. This is called an automatic residual cleanup.

When it triggers. A cleanup arms itself only when every one of the following is true:

Back-to-back protection. A cleanup may fire at most once per normal rebalance. If the cleanup itself does not reduce the residual below 5% — for example, because liquidity at the edge of the range is too thin — the bot does not keep trying. The cleanup opportunity is reset only when the next out-of-range or manual rebalance succeeds. This prevents the bot from oscillating on pools where a small residual is structurally unavoidable.

All the usual gates still apply. A cleanup still respects the throttle (minimum interval, volatility doubling), the daily rebalance cap, the swap-backoff timer, the paused state, and dry-run mode. The cleanup is simply a reason to ask for a rebalance — every safety rule downstream continues to govern whether and when it actually runs.

What you’ll see. While a cleanup rebalance is in flight, the range banner at the top of the position card turns yellow and flashes, reading “Rebalancing to Reduce Residual Wallet Coin Amount”. The resulting entry in the Activity Log is tagged “(Residual Cleanup)” so you can distinguish it from an out-of-range or manual rebalance at a glance. There is no separate Telegram alert — cleanup rebalances use the same “Rebalance Succeeded / Failed” channels as any other rebalance.

If you don’t want to wait. You can always click Rebalance Now to sweep residuals immediately. In the Rebalance dialog, widen the range by at least one percent and click OK; the leftover tokens will be folded into the fresh position.

Tuning. The 10-minute delay and 5% threshold live in app-config/static-tunables/bot-config-defaults.json under the residualCleanup group (fields delayMs and thresholdPct). These are intentionally not exposed in the Bot Configuration UI — they are cross-cutting defaults that apply to every managed position.

Range Width

The New Range Width % is initially set based on the first liquidity position detected on the wallet. To adjust it, manually create a new LP position with your desired range on 9mm Pro, then reload the app in your browser and select the new position. The bot will adopt its range width going forward.

Volatility Doubling

If 3 rebalances occur within 4× the minimum interval (e.g. 40 minutes when the minimum is 10 min), the bot enters doubling mode. Each subsequent rebalance must wait twice as long as the previous one: 10m → 20m → 40m → 80m, and so on. This prevents rapid-fire rebalancing during high volatility. Doubling mode clears automatically if no rebalance is needed for 4× the current wait, or at the daily midnight UTC reset.

Gas Cost Protection

Before each rebalance, the bot estimates gas cost in USD. If gas would exceed 0.5% of the LP position value, the rebalance is deferred and the bot retries once per hour instead of once per minute. Normal polling resumes automatically once gas drops or a rebalance succeeds. The bot always starts with the normal polling interval.

Closed Positions

When you select a closed position (zero liquidity), the bot will display its data but will not attempt to rebalance it. If you re-open a previously closed position by adding liquidity back to the same NFT on 9mm Pro, the bot treats it as brand new—duration, fees, and P&L all start from the original mint date. Recommendation: instead of re-opening a closed position, mint a fresh LP position on 9mm Pro. This gives you a clean start with accurate tracking and avoids any ambiguity in your P&L history.

Telegram Notifications

LP Ranger can send real-time alerts to your phone via Telegram. You choose which events trigger a notification:


Setup:

  1. Open Telegram and message @BotFather. Send /newbot, follow the prompts, and it will give you a bot token (looks like 123456789:ABCdefGhI...).
  2. Save the bot token to a safe place. You will need to copy it soon.
  3. Start a chat with your new bot and send any message (just type something and press Enter).
  4. In your web browser, go to: https://api.telegram.org/bot<your-bot-token>/getUpdates (replace <your-bot-token> with the token from Step 2, no brackets).
  5. In the JSON response, find your chat ID at result[0].message.chat.id — it is a numeric value near the top of the response, inside the first result entry, under message → chat → id. Copy this number.
  6. In LP Ranger, open the Telegram setup dialog from the Settings gear menu or from the wallet setup screen.
  7. Paste your bot token and chat ID, select the events you want, and click Save.
  8. Click Test to verify — you should receive a test message in Telegram.

Your bot token is encrypted on disk with the same wallet password used for your private key. It is never sent anywhere except the Telegram Bot API.

Troubleshooting

Details

Edit Initial / Lifetime Deposit

LP Ranger automatically detects the USD value of your initial deposit by looking up historical token prices at the time you minted the position. This auto-detected value appears in the Lifetime panel as the deposit amount. However, historical prices are not always available (especially for newer or low-liquidity tokens), so the app lets you enter the deposit value manually.

How it works:

A small info icon next to the deposit value tells you which source is being used: “Manually entered”, “Valued using Historical Price”, or “Valued using Current Price” (when historical prices were unavailable and the current price was used as a fallback).

Checking for Updates

LP Ranger checks GitHub for newer releases every time you open the About dialog. Click the Settings gear icon at top right in the app, then click About.

The About dialog shows the commit hash and commit date of your running copy. If a newer official release is available, a line appears below the commit row reading “Update available: X.Y.Z — Get the update”. The Get the update link opens that release’s GitHub page in a new tab. If the line reads “Up to date”, you are already on the latest release.

To retrieve and install an update:

  1. Click Get the update in the About dialog, then download the release’s .tar.gz asset from the GitHub page that opens.
  2. Stop your running LP Ranger: in the Terminal where it is running, press Ctrl+C, or run npm run stop from the project directory.
  3. Extract the new release alongside your existing install (it unpacks into a version-stamped directory such as lp-ranger-X.Y.Z/), then cd into it and run npm ci followed by npm start. Always use npm ci for production releases so the pinned dependency versions are installed exactly.
  4. Your wallet, managed positions, and settings live in app-config/, and any custom server/bot configuration you set up lives in the optional .env file at the project root. Neither is replaced by extracting a new release alongside the old one. If you want to preserve them, copy app-config/ (and .env, if it exists) from your old install into the new one before first start.

If the About dialog does not show an update notice but you believe one is available, confirm you have network access to api.github.com and reload the app.

Supported Liquidity Pool Managers

Supported Blockchains