---
description: Comprehensive configuration guide for trading bots in the pump-bot system. Apply when configuring bots.
globs: bots/*.yaml
alwaysApply: true
---

# Bot Configuration Guide

## 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.
- 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