PulseXBot Documentation

Complete reference for PulseXBot v7.0 Phase 7: Pyramid Sizing · Compound Mode · Freefall Protection · Capital Stages · Climb Protection · RSI Dynamic Sizing · Volume Monitoring · Multi-Timeframe RSI · Event-Driven Recalibration · Stuck Deploy. Every configuration setting documented with real math and worked examples. Full strategy guides: token pairing, risk profiles, budget planning. All platforms: Windows, macOS, Linux.

Quick Start

PulseXBot is a self-contained trading bot — download the zip for your operating system, edit two text files, and run the launcher. No additional software to install, no command-line tooling required on Windows.

Before You Start — Three Things You Need

The bot cannot trade until all three of these are in place. Get them ready before you download anything.

Getting PLS Into Your Wallet

If you don't have PLS yet, here are the main ways to get it into your trading wallet:

• Bridge from Ethereum — use bridge.pulsechain.com to convert ETH, USDC, or other ERC-20 tokens into their PulseChain equivalents.
• Buy on an exchange — some centralised exchanges support PulseChain withdrawals directly to a PLS address.
• Transfer from another wallet — if you already hold PLS elsewhere, simply send it to your dedicated trading wallet address.

Getting PXB — 10,000 Per Pair

PXB is the license token for PulseXBot. Every active trading pair you want to run requires 10,000 PXB held in your trading wallet. You can buy PXB two ways:

PXB contract address: 0x24698062D05D4E38190751B4708111Ff3a3ea65C

Once PXB lands in your wallet the bot detects it automatically on start. If the bot is already running, click Recheck in the dashboard — new slots activate within seconds.

Setup Steps

Downloads

1. 1
   Download for your platform

   Click the card above for your OS.

2. 2
   Extract the zip

   Right-click → Extract All. Example: C:\PulseXBot\ on Windows, ~/PulseXBot/ on Mac/Linux.

3. 3
   Create your .env file

   Copy .env.example, rename to .env, fill in your private key and RPC URLs. See → .env Setup.

4. 4
   Configure your pairs

   Open corebot-config.js. Set your tokens, TOTAL_PLS budget, and RISK_PROFILE. Leave everything else as "AUTO".

5. 5
   Start the bot

   Windows: double-click Start-PulseXBot.bat · Mac/Linux: run ./Start-PulseXBot.sh

6. 6
   Open the dashboard

   Go to http://localhost:5555 in your browser.

Requirements

Installation

🪟 Windows

1. 1
   Download

   PulseXBot-Setup.zip from pulsexbot.com

2. 2
   Extract to a folder

   Right-click the zip → Extract All → e.g. C:\PulseXBot\

3. 3
   Create your .env

   Copy .env.example → rename to .env → open in Notepad → fill in your private key.

4. 4
   Edit corebot-config.js

   Open in Notepad or VSCode. Set your trading pairs and PLS budget.

5. 5
   Start

   Double-click Start-PulseXBot.bat

6. 6
   Open dashboard

   http://localhost:5555

C:\PulseXBot\
  ├── PulseXBot.exe           ← the bot binary
  ├── Start-PulseXBot.bat     ← recommended launcher
  ├── corebot-config.js       ← your trading config
  ├── .env.example            ← template  copy and rename to .env
  ├── .env                    ← (you create this  holds private key)
  ├── .lic                    ← license tracker (do not delete or edit)
  ├── .mk                     ← key decryption file (do not delete or share)
  ├── hex-grid-state.json     ← state file per pair (auto-created)
  ├── hex-grid-logs/          ← log folder per pair (auto-created)
  └── state-backups/          ← daily backups (auto-created)

🍎 macOS (Intel + Apple Silicon)

1. 1
   Download

   PulseXBot-Setup-Mac.zip works on all Macs

2. 2
   Unzip

   Double-click in Finder. Move the folder where you want it.

3. 3
   Create .env

   cp .env.example .env then edit in any text editor.

4. 4
   Edit config

   Open corebot-config.js in any text editor.

5. 5
   Start

   ./Start-PulseXBot.sh handles quarantine flag automatically.

6. 6
   Open dashboard

   http://localhost:5555

🐧 Linux

1. 1
   Download & Extract

   unzip PulseXBot-Setup-Linux.zip -d ~/PulseXBot && cd ~/PulseXBot

2. 2
   Create .env

   cp .env.example .env && nano .env

3. 3
   Edit config

   nano corebot-config.js

4. 4
   Start

   ./Start-PulseXBot.sh

5. 5
   Keep running 24/7

   Use screen or tmux to persist across SSH disconnects. See → Linux 24/7.

.env File Setup

The .env file holds your PulseChain wallet private key and RPC endpoints. It must be in the same folder as the bot binary.

# PulseChain RPC endpoints
RPC_URL=https://rpc.pulsechain.com
RPC_URL_BACKUP=https://rpc-pulsechain.g4mm4.io

# Your trading wallet private key  KEEP THIS SECRET
PRIVATE_KEY=0xYOURPRIVATEKEYHERE

Automatic Private Key Encryption

On first start, the bot automatically encrypts your private key using AES-256-GCM and replaces the raw value with an ENC:... string. The decryption key is stored in a separate .mk file on your machine only copying .env without .mk won't work on another machine.

How to Export Your Private Key from MetaMask

1. Click the account icon in MetaMask
2. Go to Settings → Security & Privacy
3. Click Export Private Key
4. Enter your MetaMask password
5. Copy the key exactly 64 hex chars (or 66 with leading 0x)

Available RPC Endpoints

Config File Setup

Open corebot-config.js in any text editor. This is where you tell the bot which tokens to trade and how much PLS to allocate.

The Only Settings You Must Fill In

Everything Else Leave as "AUTO"

All other settings are computed from your RISK_PROFILE and live market data by the auto-tune engine. Override only when you have a specific reason. See the full Configuration Reference → for details on every setting.

Minimal Pair Example

{
  SYMBOL:         "HEX",
  TOKEN_ADDRESS:  "0x2b591e99afE9f32eAA6214f7B7629768c40Eeb39",
  TOKEN_DECIMALS: 8,
  TOTAL_PLS:      10000000,       // 10M PLS budget
  RISK_PROFILE:   "AGGRESSIVE",  // volatile token → AGGRESSIVE
  // ── everything below is AUTO ──
  BUY_OFFSETS:    "AUTO",
  SELL_LEVELS:    "AUTO",
  // ... (all other settings)
}

First Run

On first start the bot runs a calibration phase for each pair before trading begins:

1. 1
   License check

   Bot reads PXB balance from your wallet on-chain. 10,000 PXB = 1 slot. Trading won't start without it.

2. 2
   Calibration (~3 minutes)

   For each pair, the bot samples price every 5 seconds to measure ATR volatility. You'll see [CALIBRATING] in the terminal. The dashboard shows the pair as CALIBRATING. Don't stop the bot during this phase.

3. 3
   Grid seeded

   Auto-tune computes all AUTO parameters and places the grid. The log prints each level's trigger price and allocation. Trading is now live.

4. 4
   First buy

   As soon as price touches a level's trigger, the bot buys. You'll get a Telegram alert (if configured) and see the level card turn green in the dashboard.

Token Pairing Strategy

Not all tokens work the same way in a grid bot. Understanding what you're actually trading and how price movement maps to profit is the foundation of good config choices.

PulseChain-Native Volatile Tokens

Tokens like HEX, EHEX, PLSX, PDAI, INC, and PRVX are PulseChain-native assets. Their price in PLS moves with real supply and demand they pump and dump based on market sentiment, liquidity events, and trading volume. Grid trading works best here because price oscillates within a range, and the bot captures each swing.

These are your core trading pairs. Higher volatility means more level fills, more sells, more cycles. The grid earns on each round trip.

Bridged Assets (WETH, WBTC)

Wrapped ETH and Wrapped BTC on PulseChain track the global ETH/USD and BTC/USD price. Their volatility is real but lower than PulseChain-native meme tokens. They tend to move in larger, slower trends rather than rapid oscillations.

The grid still works here ETH and BTC do have meaningful daily ranges but they suit wider, fewer levels that capture larger moves rather than tight grids that fill on every micro-move.

Stablecoins Against PLS The Directional Bet

USDC is pegged to $1 USD. Its price in PLS is simply 1 ÷ PLS_USD_price. When PLS goes up in dollar value, USDC costs fewer PLS. When PLS drops, USDC costs more PLS.

The bot buys USDC when PLS is "expensive" (USDC is cheap in PLS terms) and sells USDC when PLS is "cheap" (USDC is expensive in PLS terms). You profit when PLS falls in USD value.

This is a valid hedging strategy USDC positions gain value in PLS terms during a PLS downtrend. But if you're generally bullish on PLS, these positions will sit underwater while PLS appreciates. Size them accordingly and understand they're a directional bet, not a pure volatility trade.

USDC on PulseChain uses RISK_PROFILE: "CONSERVATIVE" wide levels to catch genuine PLS price moves, not micro-oscillations. Dollar pegging means ATR will be very low (tiny day-to-day noise), so AGGRESSIVE would create levels too tight to be meaningful.

PDAI A Different Story

PDAI on PulseChain is a meme token, not a real DAI implementation. Its price is well under 1 cent and moves independently of USD. Treat it exactly like any other PulseChain-native volatile token AGGRESSIVE profile, tight grid, high cycle frequency.

Quick Reference: Token → Profile

Choosing Your Risk Profile

The RISK_PROFILE setting is the single most important config choice. It controls how aggressively the bot deploys capital, how many levels it uses, and how it responds to market conditions. Here's what each profile actually does.

What "More Levels" Actually Means

More levels doesn't mean more profit it means more capital deployed in a single downtrend. AGGRESSIVE with 6 levels can deploy the entire TOTAL_PLS budget across a -8% move. CONSERVATIVE with 3 levels spreads the same budget across a wider range, preserving more dry powder for deeper dips.

The "Stuck" Risk with AGGRESSIVE

When AGGRESSIVE fills all 6 levels in a downtrend, all capital is deployed. If price keeps falling, there's nothing left to buy the dip. The grid sits "STUCK" waiting for a recovery. CONSERVATIVE preserves the deep-DCA reserve (20% of budget) for exactly this scenario it can still buy at a -12% to -26% offset even after the main grid is full.

Summary Decision Guide

• Is it a dollar-pegged stablecoin? → CONSERVATIVE. It's a directional PLS bet, not an oscillating trade.
• Is it a bridged ETH or BTC derivative? → CONSERVATIVE. Tracks global trends, not PulseChain micro-moves.
• Is it a PulseChain-native volatile token with good liquidity? → AGGRESSIVE. Let it cycle fast and compound profits.
• Is it a PulseChain token with low liquidity or uncertain character? → BALANCED. More breathing room while you learn how it trades.
• New token you've never traded before? → BALANCED for the first week, then reassess based on how it behaves.

Budget Planning

Sizing your budget per pair is as important as choosing the right profile. Too small and gas costs eat your profit. Too large relative to liquidity and your own swaps move the market against you.

The 85% Rule

The sum of all TOTAL_PLS budgets across all pairs should be at most 85% of your wallet balance. The remaining 15% covers:

• Gas for all transactions (buys, sells, approvals)
• Deep-DCA reserves (already inside TOTAL_PLS but needs headroom in the wallet)
• RESERVE_PLS per pair (auto-set to ~200K minimum)
• Buffer for unexpected market conditions where multiple pairs might need to buy simultaneously

Minimum Viable Budget Per Pair

The minimum useful TOTAL_PLS depends on the pool's trade size and gas costs. Too small and the bot spends more on gas than it earns:

How Budget Splits Across the Grid

Understanding exactly how the bot uses your budget helps avoid surprises. The full split is:

Adding Capital Mid-Run

To increase TOTAL_PLS on a running pair: stop the bot, update the value in config, restart. The new budget takes effect on the next recalibration or reseed. Existing filled positions are preserved and reattached to the new grid automatically. The bot does not redistribute capital from existing filled levels only new buys use the updated sizing.

How Grid Trading Works

Grid trading places buy orders at fixed intervals below the current price. When price drops and fills a level, the bot holds the tokens and waits for a recovery. When price recovers past the sell target, it sells profiting from the round trip. The grid resets and repeats indefinitely.

Lifecycle of a Single Level

Partial Tier Sells (30% / 70% split)

Every filled level sells in two tiers rather than all at once. This captures both quick early profit and the full upside of bigger moves.

Tier 1 Fixed Sell (30%)

When price reaches the T1 target, the bot immediately sells 30% of the level's tokens at a fixed price. This is a guaranteed profit lock it fires regardless of what happens next, even if price immediately reverses. T1 is never a trail.

Tier 2 Trailing Sell (70%)

After T1 fires, T2 holds the remaining 70%. Once price climbs past the T2 trigger, a trailing stop activates and follows the price up. When price retreats from its peak by the trail distance, T2 sells. This captures extended pump moves that T1 would have exited too early.

Trailing Stop Sells

The trailing stop only ever moves up. Once armed, it tracks the highest price seen. The stop sits below that peak by TRAIL_DISTANCE_PCT. If price falls to the stop level, the sell fires. If price keeps rising, the stop rises with it it never drops.

Wick Filter (TRAIL_CONFIRM_POLLS)

Before the trail arms, price must stay at or above the T2 trigger for TRAIL_CONFIRM_POLLS consecutive ticks (default 2 = 10 seconds at 5s interval). A single spiked candle wick won't arm the trail at a phantom peak.

Loss-Guard Interaction and Invalidation

If the trail stop fires but the sell estimate is below the loss guard floor, the trail holds and retries every tick. If price then falls more than TRAIL_INVALIDATE_BUFFER_PCT (default 0.30%) below the stop, the trail cancels entirely and the tier re-arms at its original target it will wait for a fresh attempt when price recovers again.

Trade-Off

A tighter trail distance (TRAIL_DISTANCE_PCT 0.3%) exits quickly on small pullbacks, leaving more profit on the table for big moves. A wider distance (1.5%) rides bigger pumps but gives back more on the way down. Auto-tune scales this with ATR wider in volatile markets, tighter in calm ones.

Example

Deep-DCA Reserve Levels

A portion of the budget is held back as a reserve three extra buy levels placed well below the main grid. These are insurance for genuine crashes, not regular dips.

Activation requires all three conditions simultaneously:

• All main grid levels must be filled (grid is "full")
• Market regime must be TREND_DOWN or DCA
• 1h RSI must be below DEEP_DCA_RSI_MAX (e.g. RSI < 25 for BALANCED)

Auto-Shift Grid

When price rises above the seed and no levels are filled, the grid automatically shifts upward to follow. This prevents the bot from waiting forever with a grid anchored to a stale price far below current market.

Only fires when zero levels are filled the bot never shifts with open positions. AUTO_SHIFT_PCT sets the threshold above seed; AUTO_SHIFT_COOLDOWN_MS (default 5 minutes) prevents chasing chop by limiting shift frequency.

Stuck-Level Reduction

When a level stays filled for longer than STUCK_REDUCE_START_HOURS (default 6h) without selling, the stuck-reduction system gradually lowers its sell target toward a floor of STUCK_REDUCE_MIN_PCT (default +1.5%) over a 24-hour ramp.

This is optional STUCK_REDUCE_ENABLED defaults to false. When disabled, stuck levels wait indefinitely for full recovery. When enabled, they can exit at a smaller profit rather than waiting months for the original target.

Cycle Completion

A cycle completes when every main grid level and every deep-DCA level has been filled and fully sold. At that point:

• Cycle counter increments
• If COMPOUND_PCT is set, net profit × compound% is added to TOTAL_PLS for the next cycle
• The grid reseeds at current price (with a small RESEED_OFFSET_PCT cushion above)
• A 🎉 CYCLE COMPLETE Telegram alert fires with full P&L summary
• Auto-tune recalibrates fresh ATR and liquidity measurements for the new grid

Auto-Tune Calibration

Auto-tune is the bot's built-in calibration engine. It runs on startup (first time or after a cycle completes), every AUTOTUNE_RECAL_MS hours (default 24h on a clean grid), and whenever a regime shift is detected.

During calibration (~3 minutes) the bot samples price every 5 seconds. It measures:

• ATR average true range as a % of price, indicating current volatility
• Pool liquidity USD value in the trading pool to set slippage tolerance
• RSI to understand current momentum and set appropriate thresholds

What Auto-Tune Sets

Auto-Tune Modal (Dashboard)

Click AUTO-TUNE on any pair tab to open the live override modal. It shows every auto-tuned parameter with its current value and lets you:

• Temporary override changes take effect immediately but revert on the next 24h recalibration
• Permanent override writes the value to the state file, survives restarts and recalibrations
• Reset to AUTO reverts a manually overridden parameter back to auto-tune control

Market Regimes

The bot continuously analyses price relative to the 20-period moving average (MA20) and RSI to detect the current market regime. The regime changes how the bot buys, sells, and deploys capital.

ATR Adaptive Spacing

The ATR (Average True Range) measures typical price movement as a percentage. The bot uses it to automatically widen or tighten grid offsets and sell targets relative to current market volatility.

This means in high-volatility markets, levels are placed further apart (reducing fill frequency but improving profit per trade). In low-volatility markets, levels tighten slightly to stay relevant. The multiplier is bounded by ATR_MIN_SPACING_MULT and ATR_MAX_SPACING_MULT.

Risk Profiles

The three profiles set a complete bundle of parameters in one setting. The profile cards in the Choosing Risk Profile guide show every value each profile sets. Key differences:

Level Recycling

When the deep-DCA reserve is activated and a level fills, it's considered "deployed from reserve". After the reserve level sells, it recycles back to WAITING in the reserve pool it doesn't merge with the main grid. The capital is returned to the reserve budget and can redeploy next time the triple activation conditions are met.

If a deep-DCA level is stuck (all main levels still filled, 72h+ in BALANCED), the stuck-deploy timer fires it regardless of RSI. At that point it's no longer technically "reserve" it's treated as an emergency deploy. It still sells at its normal target and recycles normally after selling.

Partial Take-Profits Deep Dive

Tier Object Format

{ pct: 1.5,  portion: 0.30, trail: false }   // T1: sell 30% at +1.5% fixed
{ pct: 2.5,  portion: 0.70, trail: true  }   // T2: trail 70% once price hits +2.5%

Default AUTO Output (30% fixed + 70% trailing)

SELL_LEVELS: [
  { pct: 1.5,  portion: 0.30, trail: false },
  { pct: 2.8,  portion: 0.70, trail: true  }
]

Full 30/70 Worked Example

Three-Tier Example

SELL_LEVELS: [
  { pct: 1.2, portion: 0.20, trail: false },  // T1: 20% at +1.2% fixed
  { pct: 2.5, portion: 0.30, trail: false },  // T2: 30% at +2.5% fixed
  { pct: 3.5, portion: 0.50, trail: true  }   // T3: trail remaining 50%
]

Three-tier setup locks in profit at two fixed points before trailing the rest. Useful for low-liquidity tokens where getting the trail exactly right is harder.

Dashboard Display

Level card shows tiers: ✓30% ●70%. ✓ = sold, ● = waiting. The card only resets to WAITING after ALL tiers complete.

Deep-DCA Deep Dive

Budget Split Math

Why It Helps

After a genuine crash fills all main levels, the market is often at maximum fear. RSI is deeply oversold. This is precisely when buying adds the most value the reserve deploys at levels 12–26% below seed, positions the bot for the eventual recovery, and sells on the bounce well above those extreme lows.

Stuck Level Recovery Deep Dive

Reduction Math

The ramp runs from STUCK_REDUCE_START_HOURS to START_HOURS + 24 hours. At the start of the ramp, target is unchanged. At the end, target is at the floor.

When STUCK_TRAIL_TIGHTEN is true, the trail distance also tightens as the level ages making the trail more likely to fire on a small recovery rather than waiting for a full bounce.

Freefall Protection

How It Triggers

Every tick, the bot checks: has price dropped more than FREEFALL_DROP_PCT over the last FREEFALL_CANDLES candles? If yes, buying pauses immediately even if a level's trigger price is right there.

Recovery

Buying resumes when price recovers FREEFALL_RECOVERY_PCT above the low that triggered the pause. This prevents buying into a dead-cat bounce.

Auto-Tune Math

Capital Stages

As more budget is deployed, the bot automatically scales down buy sizes. This prevents committing all capital into a relentlessly declining market.

Default Values (BALANCED)

Thresholds: [0.30, 0.60, 0.85] of budget deployed. Multipliers: [1.0, 0.75, 0.50, 0]

Example

Stages reset automatically when a sell returns capital if deployment drops back below 60%, the next buy at 75% size again.

Climb Protection

How It Works

When price rises above MA20 by more than CLIMB_SENSITIVITY_PCT, the bot temporarily raises sell targets by CLIMB_EXTRA_GAIN_PCT. The moment price drops back below the MA20 threshold, targets revert immediately no persistence.

Example

RSI Dynamic Sizing

The 1-hour RSI adjusts buy size bigger bets when the market is genuinely oversold, smaller bets when overbought and likely to correct further down.

Default Values (BALANCED)

Example (base allocation = 2,000,000 PLS)

Pyramid Level Sizing

Rather than allocating equal capital to each level, the pyramid gives more capital to deeper levels. The deeper the dip, the bigger the buy maximising position size exactly when prices are most attractive.

Default Weights by Profile (3 levels)

Example BALANCED, 10M PLS, 3 main levels, gridBudget = 8,820,000

Compound Mode

After every profitable sell, a portion of the net profit is reinvested added to the budget of the next buy. Positions grow using house money over multiple cycles, without requiring extra deposits.

Multi-Cycle Compounding Example (COMPOUND_PCT = 15%)

After 17 cycles with 15% compounding, the effective budget is ~11% larger than the original pure growth from reinvesting profits with zero additional deposits. AGGRESSIVE profile auto-sets this to 25%; CONSERVATIVE and BALANCED leave it off by default.

Volume Monitoring

What It Shows

The bot tracks 1h DEX volume in real time and compares it to the 24h rolling average. The dashboard shows a live volume ratio per pair:

Volume is informational only it doesn't directly block buys or sells. Use it to contextualise price moves shown in the dashboard and candlestick chart.

Multi-Timeframe RSI

Two RSI calculations run in parallel at all times:

Why Both Matter

5-minute RSI can flash oversold on a single large candle a spike that immediately reverses. The 1-hour RSI won't move as much from a single candle. If the 5m RSI is 20 (extreme oversold) but the 1h RSI is 55 (neutral), the buy-size boost is minimal. This filters panic spikes from genuine market weakness.

When both agree (5m oversold AND 1h oversold), the RSI multiplier is applied fully maximum buy conviction on genuine market lows.

Event-Driven Recalibration

In addition to the 24h scheduled recalibration, the bot recalibrates immediately when significant market events occur:

Triggers

Event-driven recalibration only fires on a clean grid (no filled levels) to protect open positions. If levels are filled when the event occurs, the recalibration queues until all levels have sold and cycled.

Stuck Deploy

If the grid stays fully loaded all main levels filled for longer than STUCK_DEPLOY_HOURS with no deep-DCA activation, the bot deploys the deep-DCA reserve without waiting for the RSI gate. The RSI condition is bypassed because the market simply isn't recovering even though technically all capital is deployed.

How It Differs from Normal Deep-DCA

Example (BALANCED, STUCK_DEPLOY_HOURS = 72)

Loss Guard (Strict Zero)

The loss guard is a pre-sell estimate that blocks any sell whose net result after gas and slippage would fall below SELL_LOSS_GUARD_PCT (default 0 = never sell at a loss). The check runs before every auto-sell.

Three-layer defense in depth:

• Pre-swap estimate uses the DEX router to predict actual received PLS including pool slippage
• Full-cost accounting includes both the sell transaction's gas AND the original buy's gas in the cost basis
• Fail-closed if the estimate itself fails (RPC error, zero liquidity), the sell is blocked rather than proceeding on a guess

SELL_MIN_PROFIT_PCT (default 0.30%) adds an additional floor above zero the bot won't sell at breakeven, only at a meaningful net gain. The dashboard always shows "sells at ≈ XXXXX" so you can see the exact threshold for each level.

5% Pre-Swap Deviation Check

Before every buy, the bot fetches a fresh DEX quote. If this quote is more than 5% different from the last known price, the buy is skipped for this tick. This protects against sandwich attacks, flash moves, and thin pool spikes where the bot might buy at a severely unfair price.

The check fires silently you'll see "pre-buy quote shows X% slippage skipping" in the log if it blocks a buy. The bot retries on the next tick automatically.

Low-Funds Watchdog

Every tick the bot checks whether the wallet has enough PLS to execute the next pending buy. If not:

• Pair shows a low-balance warning in the dashboard
• Telegram alert fires (if lowBalance: true)
• Bot does NOT crash it keeps managing existing positions and retries when balance improves

The alert suppresses itself when all main levels are already filled in that case low balance is expected and normal, not an error.

State File Backups

State files are backed up at three points:

State Mismatch Detection

On every restart, the bot reads the token balance from the wallet and compares it to the total tracked by the state file. If they don't match within a small tolerance, the pair pauses immediately and shows STATE MISMATCH rather than trading on stale data.

See Recovery from State Mismatch → for the step-by-step fix process.

RPC Auto-Recovery

The bot tracks failure counts per RPC endpoint. After 3 consecutive failures, it switches to the backup. It checks the primary every 5 minutes and switches back when healthy. An orange SERVER badge in the dashboard shows when the backup is in use.

RPC Latency Scoring

At startup, the bot tests all configured RPC endpoints and picks the fastest. Latency is measured per request throughout the session if a previously fast endpoint starts degrading, the failover logic activates.

Atomic State Saves

Every state write goes to a .tmp file first, then atomically renames to the real path. A crash or power cut at any moment leaves the state file intact it's impossible to have a half-written, corrupted state file. If the rename fails, the old state file remains untouched.

On-Chain Sell Verification

After every sell transaction confirms, the bot queries the actual on-chain token balance and compares it to what the state file expects. Only after this check passes does the bot log the sell as complete and reset the level. If the balance doesn't match expectations, the level stays FILLED and a warning fires no false completions.

Nonce Collision Prevention

The bot tracks the last submitted transaction's nonce. Before submitting a new transaction, it checks whether the previous nonce is still pending in the mempool. If it is, the new submission is held until the pending TX resolves preventing double-submitting, nonce collisions, and stuck transactions.

60-Second Transaction Deadline

Every swap includes a 60-second on-chain expiry timestamp. If the transaction isn't mined within 60 seconds, it auto-reverts rather than executing at a stale price. The bot retries on the next tick with a fresh quote. This protects against congested mempools where old TXs would otherwise fill at prices far from when they were submitted.

Chain ID Verification

On startup, the bot queries the connected RPC to confirm it's on PulseChain (chain ID 369). If the RPC returns a different chain ID, the bot refuses to start entirely. This prevents accidentally trading on a testnet or a wrong network with real funds.

Startup State Repair

On every restart, the bot scans all level statuses for inconsistencies that can occur after an unexpected shutdown:

• Level in CLOSED status with non-zero token balance → recycled to WAITING
• Level in FILLED status with zero token balance → inspected via on-chain query, resolved
• Deep-DCA levels stuck mid-transition → reset to their correct state

Self-healing requires no manual intervention. You'll see ⚠ L3 stuck CLOSED with no tokens recycling to WAITING in the log when repair fires.

Configuration Overview

All bot settings live in corebot-config.js a plain JavaScript file in your bot folder. Open it with Notepad, Notepad++, TextEdit, VSCode, or any text editor. The file has three sections:

1. Network & dashboard chain ID, router address, dashboard port. Rarely change these.
2. Global tuning tick interval, logging, calibration timings.
3. Pairs array one config block per token you trade. This is where you spend most of your time.

Network & Dashboard Settings

Global Settings

Pair Settings Capital

Each entry in the PAIRS array configures one token. These are the identity and budget fields.

Pair Settings Grid

Pair Settings Sells

Pair Settings Safety

Pair Settings Indicators

Pair Settings Phase 6 & 7

These settings cover the advanced adaptive features. All default to "AUTO" and are calibrated from RISK_PROFILE. The global PHASE6_* flags must also be true for each feature to take effect.

Pair Settings Stuck Reduction

Adding a New Pair

Open corebot-config.js, copy an existing block inside the PAIRS array, and fill in the five required identity fields. Leave everything else as "AUTO".

{
  // ── REQUIRED  fill these in ─────────────────────────────────────────
  SYMBOL:              "MYTOKEN",
  TOKEN_ADDRESS:       "0x...your token contract...",
  TOKEN_DECIMALS:      18,           // 18 for most; 8 for HEX/WBTC; 6 for USDC
  TOTAL_PLS:           5000000,      // your budget for this pair
  RISK_PROFILE:        "BALANCED",   // CONSERVATIVE | BALANCED | AGGRESSIVE

  // ── LEAVE ALL BELOW AS "AUTO" TO START ──────────────────────────────
  BUY_OFFSETS:              "AUTO",
  RESERVE_PLS:              "AUTO",
  DEEP_DCA_BUDGET_PCT:      "AUTO",
  DEEP_DCA_OFFSETS:         "AUTO",
  DEEP_DCA_RSI_MAX:         "AUTO",
  SELL_LEVELS:              "AUTO",
  TRAIL_TRIGGER_PCT:        "AUTO",
  TRAIL_DISTANCE_PCT:       "AUTO",
  SELL_LOSS_GUARD_PCT:      "AUTO",
  SLIPPAGE_PERCENT:         "AUTO",
  MIN_LIQUIDITY_USD:        "AUTO",
  BUY_COOLDOWN_MS:          "AUTO",
  AUTO_SHIFT_PCT:           "AUTO",
  RESEED_OFFSET_PCT:        "AUTO",
  DCA_BIAS_EXTRA_PCT:       "AUTO",
  STUCK_REDUCE_ENABLED:     false,
  SELL_MIN_PROFIT_PCT:      0.30,
  TRAIL_CONFIRM_POLLS:      2,
  TRAIL_INVALIDATE_BUFFER_PCT: 0.30,
}

Common PulseChain Token Addresses

Web Dashboard

Open the dashboard at http://localhost:5555 (or your configured PORT). It refreshes automatically every 2–5 seconds via WebSocket.

Header Bar

Price Ticker

Scrolling bar below header showing live prices for PLS and all active pairs with 1h, 24h, 7d % changes and direction arrows. Click any token to jump to its pair page.

Navigation Tabs

All Pairs Overview

• Per-pair status cards price, regime, P&L, level status, budget, and quick-access buttons (Pause, Sell All, Reseed, Calibrate, Auto-Tune)
• Combined P&L card animated water-level showing total portfolio profit/loss
• 7-Day P&L chart combined realised P&L trend per pair
• Recent trade history unified buy/sell feed. Click FULL TRADE LOG for filters, cycle grouping, and per-pair breakdown
• 📊 SUMMARY full portfolio modal: total value, ROI, win rate, avg profit per sell, best/worst trade, avg hold time, weekly trade chart

Token Page

Click any pair tab to open its detail page. Left column: grid level cards + trade log. Right column: OHLC candlestick chart + stats.

Grid Level Cards

Right Column Action Buttons

Right Column Position Stats

Water-Level Cards

The animated pair cards on the overview visually represent position profit/loss status:

• Low water (≈10% of card) well above water (≥+5% profit on avg entry). Position is healthy.
• Rising water profit shrinks toward zero, water rises smoothly toward midpoint.
• Full water (≈95%) deeply underwater (below −15% from avg entry). Almost completely submerged.
• Wave speed increases the more underwater the position is. Choppier water = stormier market for that pair.
• ABOVE WATER +X% green label showing current profit vs avg entry.
• UNDER WATER −X% red label showing current loss vs avg entry.

Terminal Display

The bot renders a live terminal display in the console window. Useful when running on a VPS via SSH or for text-only monitoring.

Header Strip

💎 PULSEXBOT CORE   PULSECHAIN 369   7 PAIRS             time 14:39:21   P&L +12,990,124 PLS   WALLET 14,530,000 PLS  $97
RPC ● rpc.pulsechain.com  latency 21ms  fails 0/3                          backup: rpc-pulsechain.g4mm4.io
LICENSE  ✓ LICENSED  7 slots active  · 70,000 PXB held       10,000 PXB = 1 slot · add more to unlock extra pairs
PAIRS ● HEX ◀ PROCESSING | ● USDC | ● EHEX | ● WETH | ● PDAI | ● WBTC | ● PLSX

License Row States

Per-Pair Summary Table

License System

PulseXBot uses the PXB token for licensing. Slots are unlocked by holding PXB tokens in the bot's wallet. License checks happen on startup and every 6 hours no internet license server, no user accounts. Pure on-chain verification.

10,000 PXB is required from the very first run. There is no free trial. The bot will calibrate but won't place any buys without PXB. Buy PXB, click Recheck in the dashboard, and trading starts immediately.

Buying PXB Tokens

There are two ways to buy PXB. Both swap PLS for PXB — the difference is where the transaction is constructed.

Option A — Built-in Buy PXB button (easiest)

Click the Buy PXB button in the PulseXBot dashboard. The bot constructs and signs the swap directly from your trading wallet. No browser extension, no MetaMask, no copy-paste. Requires the bot to be running and PLS already in your wallet.

Option B — PulseX DEX (if bot is not yet running)

Go to PulseX, connect your wallet, and swap PLS for PXB manually. Use the link below or navigate to PulseX and paste the contract address into the "To" field:

https://pulsex.mypinata.cloud/ipfs/bafybeicn3lj4oandfaufxsjgu6hevu4gyp5dhxpbajurglrsrlsbv7jipi/#/

PXB contract: 0x24698062D05D4E38190751B4708111Ff3a3ea65C

Once tokens land in your trading wallet, click Recheck in the dashboard. New slots activate within seconds.

Slots Explained

Slots are calculated as floor(PXB balance / 10,000) there is no cap. Slots update live every 6 hours and on every restart.

Pairs beyond your slot count show 🔒 Slot Required in the dashboard and don't trade until more PXB is added.

If PXB balance drops (you sell some PXB), the pair with the highest config position loses its slot first. Buys pause but existing positions are still managed and sold normally.

Log Files

The bot creates a session log in the bot folder and a dedicated log folder per trading pair. All files are created automatically no configuration needed.

Session Log (Bot Folder)

Every start creates a timestamped session log: session-2026-07-24_14-44-43.log. Captures every line of terminal output with timestamps. Auto-pruned after 14 days on startup the complete record for that run.

Per-Pair Log Folder (SYMBOL-grid-logs/)

Each pair gets its own log folder, e.g. hex-grid-logs/. Files inside it:

candles-YYYY-MM.jsonl How It Works

Each line is one completed 5-minute candle in JSON:

{"t":1753401600000,"o":182.41,"h":182.94,"l":182.37,"c":182.71,"v":1603}

Fields: t = timestamp (ms), o/h/l/c = open/high/low/close in PLS, v = volume. The dashboard /api/candles endpoint reads all monthly files when you open the chart which is why chart history survives restarts and goes back months.

State Backups (state-backups/)

State files are backed up into a state-backups/ folder. Three independent tiers confirmed from bot code:

Security Checklist

• ☐ Using a dedicated trading wallet not your main or hardware wallet
• ☐ Trading wallet holds only the PLS intended for trading plus a gas buffer
• ☐ .env is NOT shared with anyone
• ☐ .env is NOT uploaded to GitHub, Google Drive, Dropbox, or any cloud
• ☐ .env is NOT in an auto-syncing folder (OneDrive, iCloud, Dropbox)
• ☐ .mk is backed up alongside .env both needed together
• ☐ .mk is NOT shared with anyone
• ☐ Private key is NOT in corebot-config.js or any other file
• ☐ Telegram BOT_TOKEN is never shared in screenshots, chats, or uploads
• ☐ Dashboard is NOT exposed to the public internet use SSH tunnel or localhost
• ☐ Bot is running on a machine you control, not shared or public
• ☐ Only trading with funds you can afford to lose

Tips Capital Sizing

Per-pair TOTAL_PLS is the budget the bot can spend on that pair. Your wallet must hold at least:

min wallet = SUM(TOTAL_PLS across all pairs) + SUM(RESERVE_PLS per pair) + ~5,000 PLS gas

With auto-tune defaults at BALANCED, RESERVE is ~200K PLS per pair. So 7 pairs × 10M PLS = 70M for grids, plus 1.4M reserve, plus gas buffer ≈ 72M minimum wallet.

Tips Choosing Pairs

Grid bots make money on volatility within a range. Best pairs share these characteristics:

• Liquid at least $50K USD pool. $200K+ is comfortable. Very thin pools mean high slippage eating profits.
• Volatile but range-bound daily ranges of 2–10% are ideal. A token that moves 0.5% a day barely generates enough swing to cover gas.
• Mean-reverting established PulseChain assets range more than pure trend tokens. Avoid tokens in sustained one-directional downtrends.
• Not in a death spiral the grid keeps buying as price falls. If the token is bleeding to zero, you accumulate more of a worthless token.
• Not parabolic a token that went 10× in a week and you're buying the top will end up with a lot of deep-stuck positions.

Tips Running on VPS

For 24/7 unattended operation, a low-cost VPS is ideal. The bot uses ~150 MB RAM per pair.

• $5–10/month VPS is plenty for a single-instance setup (2 vCPU, 2 GB RAM for 7 pairs)
• Use screen or tmux to keep running across SSH disconnects
• Pick a region with low latency to PulseChain RPCs (US East or Europe are typically best)
• Set HOST: "localhost" and use an SSH tunnel to access the dashboard privately
• Or set HOST: "0.0.0.0" and protect with a firewall rule (only your IP → port 5555)

Recovery from State Mismatch

If a pair shows STATE MISMATCH on the dashboard, the state file and wallet don't agree on token balance. Follow these steps:

1. 1
   Stop the bot

   Close the bot window or Ctrl+C. Wait for the graceful shutdown message before proceeding.

2. 2
   Inspect the state file

   Open {pair}-grid-state.json in any text editor. Compare tokenBalance (wallet) against totalTokens (state's expected total) to understand the gap.

3. 3
   Check the backup folder

   Look in state-backups/ for {pair}-grid-state.startup.json first (taken right before the last restart). If that looks corrupted, try the hourly or daily slots.

4. 4
   Restore the backup

   Copy the chosen backup over the live state file, renaming it to {pair}-grid-state.json. Keep a copy of the corrupt file before overwriting.

5. 5
   Restart and verify

   Start the bot. The self-check should pass. If still mismatched, try an older daily backup. If all backups fail, use the Manual Recovery option: clear the state file completely, let the bot treat the pair as fresh, then manually reconcile your token balances.

Tips Running on Linux 24/7

Using screen (recommended)

screen -S pulsexbot          # create named session
./Start-PulseXBot.sh         # start the bot inside it
# Press Ctrl+A then D        # detach  bot keeps running
screen -r pulsexbot          # reattach later to check
screen -ls                   # list all sessions

Using nohup

nohup ./Start-PulseXBot.sh > /dev/null 2>&1 &
ps aux | grep PulseXBot      # verify it's running

Auto-restart on crash (systemd service)

# /etc/systemd/system/pulsexbot.service
[Unit]
Description=PulseXBot Trading Bot
After=network.target

[Service]
User=yourusername
WorkingDirectory=/home/yourusername/PulseXBot
ExecStart=/home/yourusername/PulseXBot/PulseXBot
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# sudo systemctl enable pulsexbot
# sudo systemctl start pulsexbot
# sudo journalctl -u pulsexbot -f   ← live logs

Telegram Alerts

PulseXBot sends real-time alerts to Telegram buys, sells, trail activations, low balance, daily summaries. No extra packages needed.

Setup

1. Open Telegram → search @BotFather → send /newbot → copy the BOT_TOKEN
2. Search @userinfobot → send any message → copy your CHAT_ID
3. Open corebot-config.js → fill in the TELEGRAM section
4. Restart the bot → startup message arrives immediately

TELEGRAM: {
  BOT_TOKEN: "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxx",   // from @BotFather
  CHAT_ID:   "123456789",                                // from @userinfobot
  BOT_NAME:  "DevBot",   // shown at top of every alert  use different names per instance
  ALERTS: {
    buys:          true,
    sells:         true,
    trailActive:   true,
    lowBalance:    true,
    rpcFailover:   true,
    stuckLevels:   false,
    botLifecycle:  true,
    dailySummary:  true,
  },
}

Alert Types

Updating the Bot

New versions ship as updated zip files on pulsexbot.com. State files are forward-compatible your positions and history survive.

1. 1
   Back up state files

   Copy all *-grid-state.json files and the state-backups/ folder. Daily backups already happen automatically, but a manual backup before a major update is good practice.

2. 2
   Stop the bot

   Close the window or Ctrl+C. Wait for graceful shutdown.

3. 3
   Download the new version

   Get the latest zip for your platform from pulsexbot.com.

4. 4
   Replace the bot binary only

   Copy PulseXBot.exe (Windows) or PulseXBot (Mac/Linux) into your existing folder. Do not replace your .env, corebot-config.js, state files, or logs.

5. 5
   Restart

   Start normally. The new version number appears in the terminal header. Positions and history are intact.

Troubleshooting

"FATAL: PRIVATE_KEY not found in .env file"

Your .env file is missing, misnamed, or the PRIVATE_KEY line is empty. Check: the file is named exactly .env (no other extension), it's in the same folder as the binary, and the value is your 64-character hex key or an ENC:... encrypted value.

"FATAL: Private key is encrypted but could not be decrypted"

Your .env has an ENC:... value but the .mk file is missing or from a different machine. Fix: delete the ENC:... value in .env and paste your raw private key the bot re-encrypts on next start.

Dashboard shows "connecting…" / no data

Make sure the bot terminal window is still open and running. Try Ctrl+Shift+R to hard refresh the browser. Try http://127.0.0.1:5555 instead of localhost. Check that PORT in config matches the URL.

"execution reverted" errors in the log

Slippage is too tight. Increase SLIPPAGE_PERCENT by 0.5 for that pair and restart. Also check pool liquidity on dexscreener.com/pulsechain.

Bot shows "SOFT STOP" badge

No PXB detected in wallet. Click Buy PXB in the dashboard (easiest — bot swaps directly from your wallet), or buy manually on PulseX DEX at PulseX DEX using PXB contract: 0x24698062D05D4E38190751B4708111Ff3a3ea65C. Then click Recheck.

"LICENSE FILE TAMPERED" in terminal

The .lic file was edited its signature no longer matches your wallet. Fix: delete the .lic file and restart with 10,000+ PXB in wallet. The bot regenerates the file on startup.

Trail stop fired but sell was blocked by loss guard

The estimated net (after slippage and gas) is below SELL_MIN_PROFIT_PCT. The trail holds and retries every tick. Dashboard shows "Loss guard: est net −X% < 0.30% floor". If price recovers enough, it executes. To exit immediately, use the manual SELL button manual sells bypass all guards.

"pre-buy quote shows X% slippage skipping"

The DEX quote was 3%+ worse than last price. Usually means thin liquidity or a fast move. Bot retries next tick automatically. If it repeats, check pool depth or increase SLIPPAGE_PERCENT.

🔒 Slot Required on a pair

That pair needs a PXB slot. Buy more PXB via the Buy PXB button in the dashboard, or on PulseX DEX (10,000 PXB per additional pair). Click Recheck after buying.

"Insufficient wallet balance skipping buy"

Wallet is at or below RESERVE_PLS. Top up wallet with more PLS, or reduce RESERVE_PLS. The dashboard shows a low-balance warning banner.

RPC errors / timeouts

Bot auto-switches to backup RPC. If errors persist, try a different primary endpoint from the list in .env Setup →.

macOS: "cannot be opened unidentified developer"

Run ./Start-PulseXBot.sh it removes the quarantine flag automatically. Or right-click PulseXBot → Open → confirm in the dialog. One-time only.

Linux: "Permission denied"

Run chmod +x PulseXBot then try again. Or use Start-PulseXBot.sh which sets permissions automatically.

FAQ

Will the bot ever sell at a loss?

No, by default. The strict-zero loss guard blocks any auto-sell whose net result (after gas and slippage) is below cost. Stuck-reduction lowers targets down to +1.5%, but the loss guard provides the hard floor. Manual sells via the dashboard bypass all guards.

What happens if PulseChain RPC goes down?

Bot switches to backup RPC automatically and keeps trading. It polls the primary every 5 minutes and switches back when healthy. You get a Telegram alert if rpcFailover is enabled.

What if the bot crashes mid-trade?

State is persisted to disk on every change. On restart, the bot loads the last state and resumes. The startup self-check verifies wallet balance matches state if there's a mismatch, the pair pauses for manual review rather than trading on stale data.

Can I run multiple instances on the same wallet?

No. Two instances race on swap nonces and corrupt each other's state. Run one bot per wallet. For more pairs than your current slot count allows, use a second wallet with its own PXB allocation.

Can the bot lose tokens?

Tokens never leave the wallet except via swaps the bot legitimately initiates. Even if the state file is corrupted, tokens stay on-chain. The seedGrid preservation system tracks positions through every reseed and recalibration.

What happens during the 24h auto-tune recalibration?

Trading pauses for ~3 minutes while the bot samples price and recomputes AUTO parameters. Existing filled levels are preserved across the recalibration they reattach to the new grid by closest-trigger-price match. You'll see ↪ Reattached preserved fill: L1 @ ... in the log.

How do I update the bot?

Stop the bot, replace only the binary (not your .env, config, or state files), restart. State files are forward-compatible positions and history survive. See Updating → for full steps.

What does "stuck X.Xh target reduced to +1.50%" mean?

That level has been filled for X hours without selling. The stuck-reduction system has lowered the sell target. It sells when price reaches the reduced target, or when the trail fires.

Why does a SELL show "gas: 312 PLS (sell 200 + buy 112)"?

The full cost-of-trade includes both the sell gas AND the original buy's gas. T1 sells charge the full buy gas; T2 shows "buy 0" because T1 already paid it. This prevents double-counting.

What is the difference between Pause and Sell All?

Pause stops new buys but keeps managing existing positions they still sell at their targets. Sell All immediately exits all filled positions at market and reseeds. Use Pause to stop accumulating. Use Sell All to fully exit.

What does CALIBRATE do vs AUTO-TUNE?

CALIBRATE forces a fresh 3-minute calibration that re-measures ATR and liquidity, then reseeds the grid. AUTO-TUNE opens a panel to view and override individual parameters without triggering a full recalibration.

Why does Deep-DCA never activate?

All three conditions must fire simultaneously: all main levels filled + TREND_DOWN/DCA regime + RSI below DEEP_DCA_RSI_MAX. If RSI never gets oversold enough, use Stuck Deploy it bypasses the RSI gate after STUCK_DEPLOY_HOURS. Or increase DEEP_DCA_RSI_MAX directly.

Can I trade the same token on two different pairs?

No each SYMBOL must be unique. Running two EHEX pairs would cause state and accounting conflicts. One token = one pair config.

My trail fired and sold but the level card still shows FILL?

With partial tiers (30%/70%), the card shows FILL until ALL tiers complete. After T1 (30%) sells, it shows ✓30% ●70% still FILL because 70% is still open. It resets to WAIT only after the final tier sells.

What is the 60-second TX deadline?

Every swap has a 60-second on-chain expiry. If not mined in time, it reverts automatically it can never execute at a stale price. The bot retries on the next tick. This protects against sandwich attacks and mempool congestion.

Is there a maximum number of pairs?

No hard cap. Slots = floor(PXB / 10,000) with no upper limit. Each pair uses ~150 MB RAM your machine's resources are the practical limit.

What does "⚠ L3 stuck CLOSED with no tokens recycling to WAITING" mean?

The bot found a level in CLOSED status but hadn't finished recycling usually from an unexpected shutdown. The startup repair caught and fixed it automatically. No action needed.

Why does the low balance alert disappear even though my wallet is low?

If all main levels are filled, low wallet balance is expected all capital is deployed. The bot suppresses the alert to avoid false alarms. It only fires when a level is genuinely waiting to buy but can't afford to.

What does "1 buy · 1 sell" in the trade log header mean?

Today's confirmed transaction count since midnight. A partial tier sell (T1 30%) counts as one sell. A T2 trail sell counts as another. A full cycle = at least N buys + 2N sells (T1 + T2 for each of N levels).