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: Compares your total equity (cash + open positions) against the market value of your open positions alone, expressed as a percentage
Formula: (Equity / Portfolio Value) × 100 — where Portfolio Value counts open positions only (it excludes cash)
Read this carefully: because the numerator includes cash but the denominator does not, this reads at 100% or higher whenever you hold any position. The more cash you hold relative to the size of your positions, the higher it climbs (e.g. $10,000 equity ÷ $6,000 of positions = 166%). A reading near 100% means almost all of your equity is deployed into positions. It is not a 0–100% "how invested am I" gauge.
When to use:
- Spotting idle cash: "The further above 100% this reads, the more of my equity is sitting in cash rather than positions"
- Fully-invested check: "A reading close to 100% means nearly all of my equity is already in positions"
- Dynamic sizing: "Deploy cash while the reading is high, and trim positions as it falls back toward 100%"
Example Strategy:
alloc1 = State: Equity Allocation (%)
gt1 = Condition: A > B (alloc1, 150)
lt1 = Condition: A < B (alloc1, 110)
buy1 = Action: Buy (cash=$10,000, when=gt1)
sell1 = Action: Sell (sell_all_from=buy1, when=lt1)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 (%) |
| "Deploy cash when it's a large share of equity" | 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 (%)
gt1 = Condition: A > B (alloc1, 160)
lt1 = Condition: A < B (alloc1, 120)
buy1 = Action: Buy (cash=$10,000, when=gt1)
sell1 = Action: Sell (sell_all_from=buy1, when=lt1)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)