> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperoru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Understand the key building blocks of the Hyperoru trading platform

Hyperoru is built around a few core abstractions that work together to automate trading.

## AI trader

An **AI trader** is the execution unit that connects everything together. Each trader has:

* A name and display identity
* An LLM model configuration (provider, model, API key)
* A connected exchange wallet (Hyperliquid or Binance)
* A bound strategy (prompt or program)
* Signal pool triggers that decide when to analyze

You can run multiple AI traders simultaneously, each with different strategies, models, and risk profiles.

## Trading prompt

A **trading prompt** is a natural language template that tells an LLM how to make trading decisions. Prompts include:

* Market context variables (prices, positions, indicators)
* Trading rules (leverage limits, position sizing, risk management)
* Output format instructions (buy/sell/hold decision)

The platform automatically injects real-time market data into the prompt before sending it to the LLM.

## Trading program

A **trading program** is a Python class with a `should_trade(data)` method that returns a trading decision. Programs provide:

* Deterministic, reproducible behavior
* Full access to market data, indicators, and positions
* Backtesting against historical data
* Execution in a secure sandbox (no filesystem or network access)

## Signal pool

A **signal pool** groups signal definitions with a set of symbols. It defines **when** a strategy should run. Signals can detect:

* Price breakouts or breakdowns
* Open interest surges
* Funding rate spikes
* Volume anomalies
* Custom metric thresholds

Multiple signals can be combined with AND/OR logic.

## Binding

A **binding** connects a trading program to an AI trader. Each binding includes:

* The program to execute
* Signal pool triggers
* Scheduled trigger interval
* Exchange-specific configuration

One AI trader can have multiple program bindings, each triggered independently.

## Decision

Every time a strategy runs, it produces a **decision** with:

| Field                       | Description                              |
| --------------------------- | ---------------------------------------- |
| `operation`                 | `buy`, `sell`, `close`, or `hold`        |
| `symbol`                    | The trading pair (e.g., BTC, ETH)        |
| `target_portion_of_balance` | Position size as a fraction (0.0 to 1.0) |
| `leverage`                  | Leverage multiplier (1x to max)          |
| `max_price` / `min_price`   | Slippage protection limits               |
| `take_profit_price`         | Automatic take-profit level              |
| `stop_loss_price`           | Automatic stop-loss level                |
| `reason`                    | Explanation for the decision             |

## Market regime

The platform classifies current market conditions into regimes:

* **Breakout** -- high volatility with strong directional movement
* **Trending** -- sustained directional movement
* **Ranging** -- sideways price action within a range
* **Volatile** -- high volatility without clear direction
* **Quiet** -- low volatility, low volume

Strategies can use regime information to adapt their behavior.