Block Builder Reference

Complete guide to all block types in the HypaValley Block Builder with practical examples and use cases.

📊 Portfolio State Blocks

These blocks give you read-only access to your current portfolio state. Use them for risk management, position sizing, and dynamic rebalancing strategies.

State: Cash ($)

What it does: Returns the cash available in your account (not tied up in positions)

When to use:

  • Position sizing: "Only buy if I have at least $5,000 cash available"
  • Cash reserves: "Keep 20% of portfolio in cash, don't invest everything"
  • Rebalancing: "If cash drops below $10k, sell some positions"

Example Strategy:

cash1 = State: Cash
pos_qty1 = State: Position Qty (AAPL)
gt1 = Condition: A > B (cash1, 5000)
lte1 = Condition: A ≤ B (pos_qty1, 0)
and1 = Condition: AND (gt1, lte1)
buy1 = Action: Buy (symbol=AAPL, cash=$5,000, when=and1)

State: Equity ($)

What it does: Returns total account equity (cash + open positions)

When to use:

  • Risk management: "Don't let equity exceed 80% of portfolio"
  • Position limits: "Don't buy more if equity is already $90k+"
  • Dollar-based targets: "Sell when equity hits $100k"

Example Strategy:

equity1 = State: Equity
gt1 = Condition: A > B (equity1, 90000)
lt1 = Condition: A < B (equity1, 30000)
sell1 = Action: Sell (sell_all_from=buy1, when=gt1)
buy1 = Action: Buy (cash=$10,000, when=lt1)

State: Equity Allocation (%)

What it does: Calculates what percentage of your total portfolio is invested (vs cash)

Formula: (Equity / Portfolio Value) × 100

When to use:

  • Rebalancing: "Keep 60% in stocks, 40% in cash"
  • Risk control: "Never exceed 85% allocation to stocks"
  • Dynamic sizing: "If allocation < 50%, buy more. If > 80%, take profits"

Example Strategy:

alloc1 = State: Equity Allocation (%)
lt1 = Condition: A < B (alloc1, 50)
gt1 = Condition: A > B (alloc1, 85)
buy1 = Action: Buy (cash=$10,000, when=lt1)
sell1 = Action: Sell (sell_all_from=buy1, when=gt1)
💡 Why this is useful: It's relative (%) rather than absolute ($), so the same strategy works whether you have $10k or $1M.

State: Portfolio Value ($)

What it does: Returns the market value of open positions (excludes cash)

When to use:

  • Performance tracking: "Exit if portfolio drops below $95k (5% loss)"
  • Profit targets: "Close all positions when portfolio hits $120k"
  • Relative position sizing: "Risk 1% of total portfolio per trade"

Example Strategy:

portfolio1 = State: Portfolio Value
lt1 = Condition: A < B (portfolio1, 95000)
sell1 = Action: Sell (sell_all_from=buy1, when=lt1)

State: Position Qty (shares)

What it does: Returns how many shares you own of a specific symbol

When to use:

  • Averaging down: "If I already own 50 shares, buy 50 more"
  • Position limits: "Don't own more than 200 shares of any stock"
  • Scaling out: "If position > 100 shares, sell half"

Example Strategy:

pos_qty1 = State: Position Qty (AAPL)
lte1 = Condition: A ≤ B (pos_qty1, 0)
gt1 = Condition: A > B (pos_qty1, 200)
buy1 = Action: Buy (symbol=AAPL, 100 shares, when=lte1)
sell1 = Action: Sell (symbol=AAPL, qty=50, when=gt1)

State: Position Avg Cost ($)

What it does: Returns the average price you paid for a position

When to use:

  • Averaging down: "Only buy more if price is 5% below my avg cost"
  • Profit targets: "Sell when price is 10% above avg cost"
  • Break-even exits: "Sell at avg cost if losing position recovers"

Example Strategy:

source1 = Data: Ticker (AAPL, 1m)
avg_cost1 = State: Position Avg Cost (AAPL)
lt1 = Condition: A < B (source1_price, avg_cost1)
gt1 = Condition: A > B (source1_price, avg_cost1)
buy1 = Action: Buy (symbol=AAPL, 50 shares, when=lt1)
sell1 = Action: Sell (sell_all_from=buy1, when=gt1)

State: Position Value ($)

What it does: Returns the current market value of a specific position

When to use:

  • Position sizing: "Don't let any single position exceed $20k"
  • Diversification: "If AAPL position > $50k, sell some and diversify"
  • Risk per position: "Limit each position to 10% of portfolio"

Example Strategy:

pos_value1 = State: Position Value (AAPL)
gt1 = Condition: A > B (pos_value1, 20000)
sell1 = Action: Sell (symbol=AAPL, qty=50, when=gt1)

🔑 Quick Reference

Portfolio vs Position Blocks

Metric Scope Use For
Cash, Equity, Portfolio Value Entire account Overall risk management, allocation
Position Qty, Avg Cost, Position Value Single stock Per-stock limits, averaging, exits

When to Use Which Block

Your Goal Use This Block
"Keep cash reserves" State: Cash
"Don't overinvest in stocks" State: Equity or State: Equity Allocation (%)
"Rebalance to 60/40 stocks/cash" State: Equity Allocation (%) ⭐
"Risk 1% per trade" State: Portfolio Value
"Limit position size in shares" State: Position Qty
"Only average down when cheap" State: Position Avg Cost
"Cap position at $20k" State: Position Value

💡 Common Strategy Patterns

Pattern 1: Percent-of-Equity Position Sizing

source1 = Data: Ticker (SPY, 1m)
sma1 = Indicator: SMA (source1, length=50)
gt1 = Condition: A > B (source1_price, sma1)
buy1 = Action: Buy (symbol=SPY, % Equity=2, when=gt1)

Pattern 2: Dynamic Allocation Rebalancing

alloc1 = State: Equity Allocation (%)
lt1 = Condition: A < B (alloc1, 65)
gt1 = Condition: A > B (alloc1, 75)
buy1 = Action: Buy (cash=$10,000, when=lt1)
sell1 = Action: Sell (sell_all_from=buy1, when=gt1)

Pattern 3: Position-Specific Risk Management

pos_value1 = State: Position Value (AAPL)
gt1 = Condition: A > B (pos_value1, 20000)
sell1 = Action: Sell (symbol=AAPL, qty=50, when=gt1)
← Back to Tutorial