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

# Signal System

> Define market conditions that trigger strategy execution

The signal system detects market events and triggers bound strategies. Instead of running strategies on a fixed schedule, signals let you react to specific conditions — price breakouts, indicator crossovers, volume spikes, and more.

## How signals work

```mermaid theme={null}
graph TD
    A[Background Scheduler] --> B[Evaluate Signal Conditions]
    B --> C{Conditions Met?}
    C -->|Yes| D[Fire Trigger]
    C -->|No| E[Wait for Next Cycle]
    D --> F[Execute Bound Strategies]
    F --> G[Prompt or Program]
```

The background scheduler periodically evaluates all active signal pools. When a pool's conditions are satisfied, it triggers the execution of bound strategies with the relevant context.

## Signal definitions

A signal defines a single condition to monitor. Signals evaluate properties of market data and return true or false.

| Component     | Description                                                                        |
| ------------- | ---------------------------------------------------------------------------------- |
| **Indicator** | The data source to evaluate (price, RSI, MACD, volume, factor, etc.)               |
| **Operator**  | Comparison operator (`>`, `<`, `>=`, `<=`, `==`, `crosses_above`, `crosses_below`) |
| **Threshold** | The target value or reference                                                      |

### Examples

| Signal                           | Meaning                                     |
| -------------------------------- | ------------------------------------------- |
| `RSI(14) < 30`                   | RSI drops below 30 (oversold)               |
| `price crosses_above EMA(200)`   | Price crosses above the 200-period EMA      |
| `volume > 2x avg_volume(24h)`    | Volume spike exceeds 2x the 24-hour average |
| `MACD crosses_above signal_line` | Bullish MACD crossover                      |

## Signal pools

A signal pool groups multiple signals with a set of monitored symbols and defines how the signals combine.

<Tabs>
  <Tab title="AND logic">
    All signals in the pool must fire simultaneously for the trigger to activate. Use AND logic for high-confidence setups that require multiple confirmations.

    ```json theme={null}
    {
      "name": "Bullish Confluence",
      "logic": "and",
      "symbols": ["BTC", "ETH"],
      "signals": [
        {"indicator": "rsi", "period": 14, "operator": "<", "threshold": 35},
        {"indicator": "price", "operator": "crosses_above", "reference": "ema_50"},
        {"indicator": "volume", "operator": ">", "threshold": "2x_avg"}
      ]
    }
    ```
  </Tab>

  <Tab title="OR logic">
    Any single signal firing triggers the pool. Use OR logic to cast a wider net for opportunities.

    ```json theme={null}
    {
      "name": "Momentum Alert",
      "logic": "or",
      "symbols": ["BTC"],
      "signals": [
        {"indicator": "rsi", "period": 14, "operator": ">", "threshold": 75},
        {"indicator": "price_change_pct", "period": "1h", "operator": ">", "threshold": 3.0}
      ]
    }
    ```
  </Tab>
</Tabs>

## Trigger types

Strategies can be triggered in two ways, configured at the binding level:

<CardGroup cols={2}>
  <Card title="Signal-triggered" icon="bell">
    The strategy executes when the bound signal pool fires. The trigger context includes which signals activated and the current values that matched.
  </Card>

  <Card title="Scheduled" icon="calendar">
    The strategy runs on a fixed interval (e.g., every 5 minutes). No signal pool is required — execution happens on the clock.
  </Card>
</CardGroup>

Signal-triggered strategies receive additional context in the `{trigger_context}` template variable:

```json theme={null}
{
  "pool_name": "Bullish Confluence",
  "triggered_signals": [
    {"indicator": "rsi", "value": 28.5, "threshold": 35},
    {"indicator": "price vs ema_50", "value": "crossed_above"}
  ],
  "symbols_triggered": ["BTC"],
  "timestamp": "2025-01-15T14:30:00Z"
}
```

## Creating signals via API

<Steps>
  <Step title="Create individual signals">
    ```bash theme={null}
    curl -X POST https://api.production.hyperoru.com/api/signals \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "RSI Oversold",
        "indicator": "rsi",
        "period": 14,
        "operator": "less_than",
        "threshold": 30
      }'
    ```
  </Step>

  <Step title="Create a signal pool">
    ```bash theme={null}
    curl -X POST https://api.production.hyperoru.com/api/signal-pools \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Mean Reversion Setup",
        "logic": "and",
        "signal_ids": ["signal-uuid-1", "signal-uuid-2"],
        "symbols": ["BTC", "ETH", "SOL"]
      }'
    ```
  </Step>

  <Step title="Bind the pool to a strategy">
    ```bash theme={null}
    curl -X POST https://api.production.hyperoru.com/api/bindings \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "trader_id": "trader-uuid",
        "prompt_id": "prompt-uuid",
        "trigger_type": "signal",
        "signal_pool_id": "pool-uuid"
      }'
    ```
  </Step>
</Steps>

## AI-assisted signal creation

Use HyperAI to generate signal definitions from natural language:

```bash theme={null}
curl -X POST https://api.production.hyperoru.com/api/hyper-ai/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a signal pool that detects BTC breakouts above resistance with volume confirmation"
  }'
```

<Tip>
  Combine signal-triggered and scheduled strategies for the same trader. Use signals for reactive entries and schedules for periodic portfolio rebalancing.
</Tip>