Position Manager For Advanced Users

This guide provides a detailed walkthrough of every feature, panel, column, and control available in the application. It is designed to help new teammates onboard quickly and to serve as a reference for understanding how dashboard actions interact with on-chain V4 positions.

1. Dashboard Overview

The Dashboard is the central command center for tracking, managing, and analyzing automated liquidity strategies. It is designed to handle the complexities of Uniswap V4 and compatible CLMM (Concentrated Liquidity Market Maker) protocols.

Key Features

• Real-time Data Merging: The dashboard intelligently merges data from multiple sources. It combines on-chain state (balances, current ticks, fee tiers) with off-chain metadata (strategy notes, team configurations).

• Auto-Refresh & Polling:

  • Interval: Strategy rows automatically poll for updates every 10 seconds.

  • Mechanism: Background polling ensures that balances and status indicators remain current without requiring a page reload.

  • Manual Override: You can trigger an immediate update using the "Force Push" action if you suspect on-chain data has changed recently (e.g., after a transaction).

• V4 Exclusive Architecture: The system is tailored for V4’s "Bin" architecture, which differs significantly from V3’s continuous tick ranges. It supports discrete price buckets and dynamic hooks.

• Context-Aware Inference: Values such as fee tiers and network details are often inferred directly from the pool contract state or the traded token pair, minimizing configuration errors.

2. Toolbar, Filters & Layout Controls

Located immediately above the strategies table, the toolbar provides powerful tools to organize and filter your view.

Persistence

Your preferences are saved. Browser storage is used to remember your active filters, column visibility settings, and pagination choices. When you return to the dashboard, you pick up exactly where you left off.

Filter Options

• Free Text Search: The "Filter positions by pair…" input allows you to search for specific token symbols (e.g., "ETH", "USDC"). This matches against the tokens in the Pair column.

• Faceted Chips:

  • Network: Filter by blockchain network (e.g., Base, BSC). Only networks with active strategies are listed.

  • Status: Filter by operational state (e.g., Active, Paused, Closed).

  • Archived: Toggle the visibility of archived strategies to keep your main view clean.

  • Type: Filter by strategy structure, such as Simple (standard liquidity) or Farm (masterchef-staked positions).

Layout Customization

• View Menu (Gear Icon): This dropdown allows you to toggle the visibility of every column in the table. You can hide less relevant metrics (like specific fee tiers) or enable advanced ones (like specific tick ranges) to tailor the workspace to your specific role.

3. Strategy Columns: A Deep Dive

Each column in the dashboard is designed to answer a specific question about your position.

Column	Description & Technical Detail
Dex	Displays the exchange provider (e.g., Uniswap V4, PancakeSwap V4, SquadSwap). Visual: Appears as an icon info-badge. Logic: Inferred from the factory address used to deploy the strategy.
Network	The blockchain network where the strategy is deployed (e.g., Base, BSC). Filter: Faceted filtering is available for this field.
Pair	The trading pair (e.g., WETH/USDC). Hover: Shows full token names and addresses.
Fee Tier	The swap fee percentage earned on trades. SquadSwap Specific: For SquadSwap strategies, this may show a split view (Current Fee / Default Fee) fetched dynamically from the SquadPair contract.
Bin Range	The specific range of active bins for the position. V4 Context: Unlike V3's continuous range, this defines the discrete buckets where your liquidity is active.
Price Range	A visual bar showing the current price relative to your position's min/max range. Colors: Green indicates the price is in range (earning fees). Red indicates out of range.
Slippage	The maximum allowed slippage for rebalancing actions, expressed as a percentage. Default: Typically defaults to 0.5% but is configurable during strategy creation.
Daily Repositions	Shows the number of automated rebalancing actions triggered today versus the daily limit (e.g., 2 / 5).
Amounts	The current token breakdown of the position (e.g., 1.2 ETH + 4000 USDC). Hover: Displays the real-time USD equivalent of the holdings based on current oracle prices.
Unclaimed Fees	Realized fees that are sitting in the contract but haven't been claimed yet. Hover: Shows the USD value of these fees. Sorting: Can be sorted by total USD value.
Efficiency	Capital Efficiency Metric. Calculated as: Efficiency = (Total Fees Earned / Position Limit USD) * 100 This metric helps identify which strategies are generating the most return per dollar of capital deployed.
Position Status	The overall health of the strategy. Active: Current tick is within the Bin Range. Inactive: Price has moved outside the range; earning stops. Refreshing: A "Force Push" or automated update is in progress. Warning: Issues like missing placement references or blockchain data connection errors.
Type	The architectural type of the strategy. Simple: Standard V4 liquidity position. Farm: Liquidity is staked in a MasterChef contract to earn additional farming rewards.
Status Switch	A toggle to Active or Paused. Logic: Flipping this switch sends an on-chain transaction to start/stop the automation bot. It does not withdraw liquidity. UX: Optimistic updates are used; if the transaction fails, the switch reverts. Requires switching your wallet to the strategy's network.
Note	Internal memos. Hovering shows the full text. Useful for tracking "why" a strategy was created.

4. Quick Actions

The inline action bar (rightmost column) allows you to manage the strategy contextually.

1. Liquidity Info (Chart Icon)

   • Opens a deep link to a detailed analytics page for this specific NFT position.

   • Useful for analyzing historical performance graphs and individual trade data.

2. Add Liquidity (Plus Icon)

   • Opens a modal to deposit more tokens into the existing strategy bins.

   • Smart Check: Verifies you have sufficient balances and allowance before submitting.

3. Close Position (X Icon)

   • Effect: Withdraws all liquidity and unclaimed fees to your wallet.

   • Status: Effectively ends the strategy lifecycle, though the history remains.

4. Set Note (Notebook Icon)

   • Attach a text note to the strategy. This is visible to all team members and searchable.

5. Force Push (Refresh Icon)

   • Use Case: Use this if you know a transaction succeeded but the dashboard hasn't updated yet.

   • Mechanism: Triggers a backend job to re-index the strategy data from the blockchain immediately. No gas required.

5. V4 Strategy Lifecycle

Managing a V4 strategy is a cyclical process of creation, monitoring, and adjustment.

Phase 1: Creation

Click Add Strategy to open the wizard.

1. Scope: Choose Public (open to public team) or Private (your organization).

2. Type:

   • Simple: Standard liquidity provision.

   • Farm: Choose this if the DEX supports MasterChef V3 farming. Requires entering the farm address.

3. DEX & Pair: Select the protocol (e.g., PancakeSwap V4) and the token pair. The system will auto-load available fee tiers.

4. Configuration:

   • Bin Step/Width: Define how granular your checks are.

   • Slippage: Set your tolerance (default 0.5%).

   • Daily Update Limit: Cap the max automated rebalances per day to control gas costs.

5. Network Switch: If your wallet is on the wrong chain, the wizard will prompt you to switch automatically before confirming.

Phase 2: Funding (Add Liquidity)

Once created, the strategy is empty. Use Add Liquidity to deposit the initial corpus.

• You must approve the tokens for the strategy contract.

• The UI handles the math to proportion tokens based on the current price tick.

Phase 3: Monitoring & Automation

• Watch the Position Status.

• The automation bot checks the position continuously. If the price moves out of your configured Bin Range, and the Status Switch is Active, the bot may attempt to rebalance (withdraw and re-deposit in the new range) depending on your strategy rules.

Phase 4: Adjustment & Closing

• Inactive? If the market moves wildly, you might end up "Inactive". usage choice:

  • Wait: If you believe price will revert.

  • Manual Rebalance: Use "Close" then create a new strategy, or wait for the bot.

• Exit: Use Close Position to sweep user funds back to your wallet.

6. Authentication & Access

Security is paramount. We support three distinct tiers of access control.

Method 1: Web3 Wallet (SIWE) - Recommended

Sign-In with Ethereum (SIWE) provides a cryptographic proof of identity.

1. Click Sign in with Ethereum.

2. Select your wallet (MetaMask, Coinbase, etc.).

3. Signature: You will be asked to sign a message like Sign to login to Position Manager....

   • Security: This signature costs 0 gas and does not grant transaction permissions. It purely proves you own the wallet address.

Method 2: Email

• Email Registration: Users can sign up and log in using their email address. Standard credential-based access for those who prefer not to use a wallet or social provider.

7. Automation Gas & Maintenance

For the automation bots to manage your positions (rebalancing, compounding, etc.), you must maintain a Gas Balance for your team or organization.

How it Works

• Automation Gas: This is separate from the gas you pay for manual transactions (like "Add Liquidity"). It is used by the backend bots to pay for on-chain rebalancing.

• Gas Deposit: You must deposit native tokens (ETH, BNB, etc. depending on the network) into your team's gas vault.

⚠️ Critical Requirement

Deposits must be made exclusively through the Position Manager website.

• Do not send funds directly to strategy contracts or individual bot addresses.

• Using the official Deposit Gas interface ensures that your transaction is correctly indexed by our backend and credited to your team's automation budget immediately.

• Failure to use the website portal may result in the automation pausing due to "Insufficient Gas" even if you have sent funds elsewhere.

Monitoring Gas Usage

• You can track your gas consumption in the Strategy History view.

• Every automated action logs the Gas Used and the Gas Fee incurred at that specific block's effective price.