From fb2903b013ae08daa318a38620785481fc1782fc Mon Sep 17 00:00:00 2001
From: smypmsa <antonsauchyk@gmail.com>
Date: Tue, 15 Jul 2025 14:10:07 +0000
Subject: [PATCH] docs: improve cursor rules (bots)

---
 .cursor/rules/bots.mdc | 132 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 127 insertions(+), 5 deletions(-)

diff --git a/.cursor/rules/bots.mdc b/.cursor/rules/bots.mdc
index 3e6df60..32d7a45 100644
--- a/.cursor/rules/bots.mdc
+++ b/.cursor/rules/bots.mdc
@@ -1,8 +1,130 @@
+---
+description: Comprehensive configuration guide for trading bots in the pump-bot system. Apply when configuring bots.
+globs: ["bots/*.yaml"]
+alwaysApply: true
+---
+
 # Bot Configuration Guide
 
-- YAML files in this directory define configuration for different bot strategies and behaviors.
+## Overview
+
+- YAML files in the `bots/` directory define configurations for different bot strategies and behaviors.
 - Each file specifies parameters for a specific bot instance or strategy.
-description:
-globs:
-alwaysApply: false
----
+- Configurations control execution parameters, trading strategies, risk management, and connection settings.
+
+## Required Configuration Sections
+
+### Bot Identification and Connection Settings
+
+```yaml
+name: "bot-name"               # Unique identifier for the bot
+env_file: ".env"               # Environment file for secrets
+rpc_endpoint: "${ENV_VAR}"     # Solana RPC endpoint
+wss_endpoint: "${ENV_VAR}"     # Solana WebSocket endpoint
+private_key: "${ENV_VAR}"      # Private key for transactions
+enabled: true                  # Enable/disable bot without removing config
+separate_process: true         # Run in a separate process
+```
+
+### Trading Parameters
+
+```yaml
+trade:
+  buy_amount: 0.0001           # Amount of SOL to spend (in SOL)
+  buy_slippage: 0.3            # Maximum price deviation for buys (0.3 = 30%)
+  sell_slippage: 0.3           # Maximum price deviation for sells (0.3 = 30%)
+
+  # Exit strategy
+  exit_strategy: "time_based"  # Options: "time_based", "tp_sl", "manual"
+  take_profit_percentage: 0.2  # Required for "tp_sl" strategy (0.2 = 20%)
+  stop_loss_percentage: 0.2    # Required for "tp_sl" strategy (0.2 = 20%)
+  max_hold_time: 60            # Maximum hold time in seconds
+```
+
+### Listener Configuration
+
+Specify one of the following listener types:
+
+#### Geyser (Fastest Updates)
+
+```yaml
+geyser:
+  endpoint: "${ENV_VAR}"
+  api_token: "${ENV_VAR}"
+  auth_type: "x-token"         # or "basic"
+```
+
+#### Logs Listener
+
+```yaml
+logs:
+  program_id: "${PROGRAM_ID}"  # Program to monitor
+  refresh_interval: 1          # Polling interval in seconds
+```
+
+#### Blocks Listener
+
+```yaml
+blocks:
+  refresh_interval: 1          # Block polling interval in seconds
+```
+
+#### PumpPortal Listener
+
+```yaml
+pumpportal:
+  endpoint: "${PP_ENDPOINT}"   # PumpPortal API endpoint
+  api_key: "${PP_API_KEY}"     # API key for authentication
+```
+
+### Filters
+
+```yaml
+filters:
+  listener_type: "geyser"      # One of: "logs", "blocks", "geyser", "pumpportal"
+  max_token_age: 10            # Maximum age of tokens to consider (in seconds)
+  min_liquidity_sol: 0.1       # Minimum liquidity in SOL
+  exclude_tokens: ["TOKEN1", "TOKEN2"]  # Tokens to exclude
+```
+
+### Priority Fees (Optional)
+
+```yaml
+priority_fees:
+  enabled: true                # Enable priority fees
+  fixed_amount: 10000          # Fixed fee amount in lamports
+  extra_percentage: 0.1        # Extra percentage of transaction cost (0.1 = 10%)
+  hard_cap: 100000             # Maximum fee cap in lamports
+```
+
+### Error Handling and Retries (Optional)
+
+```yaml
+retries:
+  max_attempts: 3              # Maximum retry attempts
+  backoff_factor: 1.5          # Backoff multiplier between retries
+  initial_wait: 1              # Initial wait time in seconds
+```
+
+### Cleanup Settings (Optional)
+
+```yaml
+cleanup:
+  mode: "after_sell"           # Options: "disabled", "on_fail", "after_sell", "post_session"
+  keep_min_balance: true       # Keep minimum balance in accounts
+```
+
+## Validation Rules
+
+- Numeric values must be within specified ranges (e.g., slippage between 0-1)
+- Required fields must be present and correctly formatted
+- Enum-like fields must use valid values from predefined options
+
+## Examples
+
+See sample configurations in the `bots/` directory:
+- @bot-sniper-1-geyser.yaml: Fast trading using Geyser stream
+- @bot-sniper-2-logs.yaml: Trading based on log monitoring
+- @bot-sniper-3-blocks.yaml: Trading based on block monitoring
+- @bot-sniper-4-pp.yaml: Trading using PumpPortal integration
+