---
description: Core trading functionality including buy/sell operations, position management, and execution strategies. Apply when working with trading logic or transaction execution.
globs: src/trading/*.py
alwaysApply: true
---

# Trading System Guide

## Overview

The trading module forms the core of the pump-bot's execution capabilities, handling token purchases, sales, position management, and trading strategy implementation. This system translates token detection events into actual on-chain transactions.

## Core Components

### Trading Coordinator

@src/trading/trader.py implements the `PumpTrader` class which:
- Orchestrates the entire trading lifecycle
- Manages token detection to execution flow
- Implements risk management controls
- Coordinates buy and sell operations
- Handles position tracking and reporting

```python
# Example usage
trader = PumpTrader(config, client, wallet)
await trader.process_token(token_info)
```

### Buy Operations

@src/trading/buyer.py provides the `TokenBuyer` class:
- Implements token purchase logic
- Handles slippage calculation and management
- Creates and submits buy transactions
- Validates transaction success

### Sell Operations

@src/trading/seller.py implements the `TokenSeller` class:
- Manages token selling operations
- Implements various exit strategies
- Handles profit calculation and optimization
- Ensures proper transaction construction

### Position Management

@src/trading/position.py offers position tracking:
- Records entry and exit prices
- Calculates profit/loss metrics
- Manages position state throughout lifecycle
- Implements risk management boundaries

### Base Abstractions

@src/trading/base.py defines core abstractions:
- Common interfaces for trading components
- Shared data structures
- Type definitions and constants
- Interface contracts for strategy implementations

## Trading Strategies

The system supports multiple exit strategies:

1. **Time-Based**: Automatically sells after a configurable holding period
2. **TP/SL**: Uses Take Profit / Stop Loss targets to manage exits
3. **Manual**: Requires explicit sell commands

```yaml
# Configuration example
trade:
  exit_strategy: "tp_sl"
  take_profit_percentage: 0.2
  stop_loss_percentage: 0.2
```

## Common Trading Flows

| Operation | Flow |
|-----------|------|
| Token Purchase | Detection → Validation → Buy Transaction → Position Creation |
| Token Sale | Strategy Trigger → Position Update → Sell Transaction → Cleanup |
| Error Handling | Error Detection → Transaction Retry → Position Closure → Cleanup |

## Related Files

- @src/trading/trader.py: Main trading coordination
- @src/trading/buyer.py: Buy transaction implementation
- @src/trading/seller.py: Sell transaction implementation
- @src/trading/position.py: Position tracking and management
- @src/trading/base.py: Core abstractions and interfaces