starchild-ai-agent/@1363/position-snapshot

Position Snapshot

Generate OHLC candlestick charts overlaid with live position data — entries, limit orders, PnL, and custom zones.

When To Use

• User asks to see their position on a chart
• User wants a visual of where their orders are relative to price action
• User says "show me where we are" or "chart my position"

Workflow

1. Gather position data — call hl_account() (or orderly_positions()) to get current position: entry price, size, side, uPnL, leverage, liquidation price
2. Gather open orders — call hl_open_orders() to get resting limit orders
3. Fetch OHLC data — call hl_candles(coin=ASSET, interval="4h", lookback=336) for 14 days of 4H candles (adjust interval/lookback to user preference)
4. Run the render script — pass data as JSON args to scripts/render_position_chart.py
5. Present the chart — display from output/ directory

Render Script

python skills/position-snapshot/scripts/render_position_chart.py \
  --coin BTC \
  --side short \
  --entry 72837 \
  --size 0.01286 \
  --leverage 10 \
  --pnl 21.73 \
  --roe 23.2 \
  --current-price 71231 \
  --liq-price 132641 \
  --candles candles.json \
  --orders orders.json \
  --zones '{"External Range Liq": [72600, 75300]}' \
  --output output/position_snapshot.png

Parameters

| Param | Required | Description | |-------|----------|-------------| | --coin | ✅ | Asset symbol (BTC, ETH, etc.) | | --side | ✅ | Position side: long or short | | --entry | ✅ | Entry price | | --size | ✅ | Position size in base asset | | --leverage | ✅ | Leverage multiplier | | --pnl | ✅ | Unrealized PnL in USD | | --roe | ✅ | Return on equity % | | --current-price | ✅ | Current mark price | | --liq-price | No | Liquidation price (shown if provided) | | --candles | ✅ | Path to JSON file with OHLC candle data (array of {t, o, h, l, c}) | | --orders | No | Path to JSON file with open orders (array of {price, size, side}) | | --zones | No | JSON string of named price zones: {"name": [low, high]} | | --output | No | Output path (default: output/position_snapshot.png) | | --interval | No | Label for candle interval (default: 4H) | | --title | No | Custom chart title |

Candle JSON format

[{"t": 1772740800, "o": 70875.5, "h": 71530.4, "l": 70805.9, "c": 71231.2}, ...]

Orders JSON format

[{"price": 73800, "size": 0.00235, "side": "sell"}, ...]

Customization

• Colors: Dark theme by default. Green/red candles, gold entry, cyan current price, orange limit orders.
• Zones: Pass named zones as JSON — they render as shaded regions with labels.
• Side-aware: Long positions show entry below current (green PnL arrow), short positions show entry above.
• Info box: Auto-generated summary panel with position details, open order count, and zone labels.

Notes

• Works with any exchange data — just needs candles in {t, o, h, l, c} format
• Hyperliquid candles from hl_candles() use this format natively
• For Orderly/other exchanges, transform to same schema before passing
• The script is self-contained — no network calls, all data passed via args/files