CryptoTrading/AGENTS.md

# AGENTS.md - AI Coding Agent Guidelines for TradeFinder

> Automated crypto trading system for BTC/ETH perpetual futures on Binance USDM.

## Quick Reference

| Task | Command |
|------|---------|
| Install | `uv pip install -e ".[dev]"` (or `pip install -e ".[dev]"`) |
| All tests | `pytest` |
| Single test | `pytest tests/test_config.py::TestOrderRequest::test_valid_limit_order -v` |
| Test file | `pytest tests/test_config.py -v` |
| Test by keyword | `pytest -k "test_valid" -v` |
| Lint | `ruff check .` |
| Lint fix | `ruff check . --fix` |
| Format | `ruff format .` |
| Type check | `mypy src/` |
| Full check | `ruff check . && ruff format --check . && mypy src/ && pytest` |

## Build & Environment

- **Python**: 3.12+ required (pandas-ta requires 3.12+)
- **Build**: `hatchling` via `pyproject.toml`
- **Prefer `uv`**: 10-100x faster than pip

```bash
uv venv .venv --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"
```

## Testing

- `asyncio_mode = "auto"` - no `@pytest.mark.asyncio` needed
- Type hints required: `def test_xxx(self) -> None:`
- Integration tests marked with `@pytest.mark.integration` (require testnet API keys)

## Linting & Type Checking

**Ruff** (line-length: 100, target: py312):
- Rules: `E`, `W`, `F`, `I`, `B`, `C4`, `UP`

**MyPy**: `strict = true`, uses `pydantic.mypy` plugin

## Code Style

### Imports (isort-ordered)
```python
from abc import ABC, abstractmethod        # 1. stdlib
from decimal import Decimal

import httpx                               # 2. third-party

from tradefinder.adapters.types import Order  # 3. first-party
```

### Type Hints (Required - strict mypy)
```python
async def get_balance(self, asset: str = "USDT") -> AccountBalance: ...
def cancel_order(self, order_id: str | None = None) -> Order: ...
list[str]       # NOT List[str]
dict[str, Any]  # NOT Dict[str, Any]
```

### Numeric Values - Always Decimal
```python
price = Decimal("50000.00")   # String input for precision
# NEVER: price = 50000.00     # Float loses precision
```

### Data Structures
```python
@dataclass
class Position:
    symbol: str
    quantity: Decimal
    raw: dict[str, Any] = field(default_factory=dict)

class Settings(BaseSettings): ...  # Pydantic for config/validation only
```

### Enums
```python
class Side(str, Enum):
    BUY = "BUY"
    SELL = "SELL"

params["side"] = request.side.value  # Use .value for API calls
```

### Logging (structlog)
```python
logger = structlog.get_logger(__name__)
logger.info("Order created", order_id=order.id, symbol=symbol)
# NEVER: logger.info(f"API Key: {api_key}")  # No secrets in logs!
```

### Async Patterns
```python
async def connect(self) -> None:
    self._client = httpx.AsyncClient(timeout=30.0)

async def disconnect(self) -> None:
    if self._client:
        await self._client.aclose()
```

### Error Handling
```python
class ExchangeError(Exception): pass
class AuthenticationError(ExchangeError): pass

try:
    await self._request(...)
except httpx.RequestError as e:
    raise ExchangeError(f"Request failed: {e}") from e
```

### Naming Conventions
| Type | Convention | Example |
|------|------------|---------|
| Modules | snake_case | `binance_usdm.py` |
| Classes | PascalCase | `BinanceUSDMAdapter` |
| Functions/Variables | snake_case | `get_open_orders` |
| Constants | UPPER_SNAKE | `MAX_LEVERAGE` |
| Private | leading underscore | `_client`, `_sign()` |

## Project Structure

```
src/tradefinder/
    adapters/       # Exchange connectivity (base.py, binance_usdm.py, binance_spot.py, types.py)
    core/           # Core engine (config.py, regime.py)
    data/           # Market data (fetcher.py, storage.py, streamer.py, validator.py, schemas.py)
    strategies/     # Trading strategies (base.py, signals.py)
    ui/             # Streamlit dashboard
tests/
    test_*.py       # Test files
```

## Security Rules (CRITICAL)

1. **NEVER commit `.env` or secrets** - `.gitignore` enforces this
2. **NEVER log API keys** - mask sensitive data
3. **Use `SecretStr`** for credentials in Pydantic settings
4. **Use `Decimal`** for all financial values - never `float`
5. **Validate trading mode** before any exchange operations

## Common Patterns

```python
# Configuration
from tradefinder.core.config import get_settings
settings = get_settings()

# Creating orders
request = OrderRequest(
    symbol="BTCUSDT", side=Side.BUY, position_side=PositionSide.LONG,
    order_type=OrderType.LIMIT, quantity=Decimal("0.001"), price=Decimal("50000"),
)
request.validate()

# Exchange adapter
adapter = BinanceUSDMAdapter(settings)
await adapter.connect()
await adapter.configure_hedge_mode(True)
await adapter.configure_margin_type("BTCUSDT", MarginType.ISOLATED)
await adapter.disconnect()
```