hypella-strategies 1.0.1
Standard strategies library for the Hypella execution platform
Requires Python: >=3.9
Keywords: trading, crypto, hyperliquid, algo, strategies

# Hypella Strategies

A standard library of **open-source trading strategies** designed for the **Hypella execution platform**, built exclusively for Hyperliquid.

Strategies in this repository act as **signal generators** and are executed using Hypella’s managed execution and risk engine.

---

## Strategy Architecture

Strategies in this repository are responsible for **entry signal generation only**.

All position execution, exits, and risk management are handled by the **Hypella execution layer**, ensuring consistent behavior and enforced safety guarantees across all strategies.

This separation allows:
- reproducible and auditable strategy logic
- standardized risk controls
- safe execution without exposing private keys
- configurable risk preferences per user

---

## Execution & Risk Management

Hypella applies a standardized and configurable risk framework to all strategies, including:

- mandatory stop-loss on every position
- take-profit via fixed target or trailing stop
- optional breakeven logic with partial position closes
- configurable position sizing per strategy

Strategies do not manage exits or capital directly. Exits are triggered by the risk engine (SL/TP/trailing/breakeven) rather than strategy logic.

### Default Risk Model

- Mandatory stop-loss on every position
- Take-profit via:
    - fixed percentage target or
    - trailing stop (optional activation after a defined profit threshold)
- Optional breakeven logic:
    - partial position close at a defined profit level
    - stop-loss moved to entry or predefined offset
    - trailing stop enabled for the remaining position

### Customization

Users can adjust risk parameters per strategy, including:
    - stop-loss distance
    - take-profit method
    - trailing activation threshold
    - breakeven behavior
    - position sizing

This ensures consistent execution quality while allowing traders to adapt risk to their preferences.

---

## Repository Structure

Strategies are organized into individual folders under `hypella_strategies/strategies/`.

The repository uses a scalable registry system with support for sub-registries.

- `hypella_strategies/registry.yaml`  
  Main entry point including all registered strategies.

- `hypella_strategies/strategies/<strategy_name>/registry.yaml`  
  Strategy-specific metadata and configuration.

- `hypella_strategies/strategies/<strategy_name>/strategy.py`  
  Strategy implementation (signal logic only).

Each strategy folder also includes a dedicated `README.md` describing its logic, use cases, and risk profile.

---

## Installation

```bash
pip install hypella-strategies
```

## Available Strategies

- **Trend Rider**: A trend-following strategy designed to capitalize on strong directional markets. It enters positions only when multiple trend and momentum indicators align, aiming to stay in trades during sustained moves while avoiding choppy conditions.
- **Bounce Recovery**: A mean-reversion strategy designed to capture controlled pullbacks and oversold conditions. Aim to profit from short-term price rebounds while applying strict risk controls to avoid prolonged drawdowns.
- **Volatility Breakout**: A strategy designed to trade sudden expansions in volatility after periods of compression. Aim to capture fast, directional moves triggered by volatility regime shifts.

## Contributing

Contributions are welcome.

To add a new strategy:
1. Create a new folder under `hypella_strategies/strategies/`.
2. Implement your strategy class by inheriting from `Strategy` base class.
3. Add a `registry.yaml` file with strategy metadata.
4. Validate your registry file using the included script:
   ```bash
   # Using installed CLI
   hypella-validate-strategies hypella_strategies/strategies/<your_strategy>/registry.yaml
   
   # Or using poetry during development
   poetry run python hypella_strategies/validation.py hypella_strategies/strategies/<your_strategy>/registry.yaml
   ```
5. Register your strategy by adding its sub-registry path to `hypella_strategies/registry.yaml`.

**All strategies should:**
- generate entry signals only
- remain stateless
- avoid embedding execution or risk logic

## Disclaimer

Strategies provided in this repository are open-source and intended for systematic trading experimentation.
They do not constitute financial or investment advice.
Trading involves risk, and users are fully responsible for their configuration and capital allocation.