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
- Gather position data — call
hl_account() (or orderly_positions()) to get current position: entry price, size, side, uPnL, leverage, liquidation price
- Gather open orders — call
hl_open_orders() to get resting limit orders
- Fetch OHLC data — call
hl_candles(coin=ASSET, interval="4h", lookback=336) for 14 days of 4H candles (adjust interval/lookback to user preference)
- Run the render script — pass data as JSON args to
scripts/render_position_chart.py
- 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
1---2name: 1363-position-snapshot3description: Generate OHLC candlestick charts with position overlays — entry price, open limit orders, PnL, and liquidity zones. Use when the user wants a visual snapshot of their current trading position on a price chart.4---56# Position Snapshot78Generate OHLC candlestick charts overlaid with live position data — entries, limit orders, PnL, and custom zones.910## When To Use1112- User asks to see their position on a chart13- User wants a visual of where their orders are relative to price action14- User says "show me where we are" or "chart my position"1516## Workflow17181. **Gather position data** — call `hl_account()` (or `orderly_positions()`) to get current position: entry price, size, side, uPnL, leverage, liquidation price192. **Gather open orders** — call `hl_open_orders()` to get resting limit orders203. **Fetch OHLC data** — call `hl_candles(coin=ASSET, interval="4h", lookback=336)` for 14 days of 4H candles (adjust interval/lookback to user preference)214. **Run the render script** — pass data as JSON args to `scripts/render_position_chart.py`225. **Present the chart** — display from `output/` directory2324## Render Script2526```bash27python skills/position-snapshot/scripts/render_position_chart.py \28 --coin BTC \29 --side short \30 --entry 72837 \31 --size 0.01286 \32 --leverage 10 \33 --pnl 21.73 \34 --roe 23.2 \35 --current-price 71231 \36 --liq-price 132641 \37 --candles candles.json \38 --orders orders.json \39 --zones '{"External Range Liq": [72600, 75300]}' \40 --output output/position_snapshot.png41```4243### Parameters4445| Param | Required | Description |46|-------|----------|-------------|47| `--coin` | ✅ | Asset symbol (BTC, ETH, etc.) |48| `--side` | ✅ | Position side: `long` or `short` |49| `--entry` | ✅ | Entry price |50| `--size` | ✅ | Position size in base asset |51| `--leverage` | ✅ | Leverage multiplier |52| `--pnl` | ✅ | Unrealized PnL in USD |53| `--roe` | ✅ | Return on equity % |54| `--current-price` | ✅ | Current mark price |55| `--liq-price` | No | Liquidation price (shown if provided) |56| `--candles` | ✅ | Path to JSON file with OHLC candle data (array of `{t, o, h, l, c}`) |57| `--orders` | No | Path to JSON file with open orders (array of `{price, size, side}`) |58| `--zones` | No | JSON string of named price zones: `{"name": [low, high]}` |59| `--output` | No | Output path (default: `output/position_snapshot.png`) |60| `--interval` | No | Label for candle interval (default: `4H`) |61| `--title` | No | Custom chart title |6263### Candle JSON format64```json65[{"t": 1772740800, "o": 70875.5, "h": 71530.4, "l": 70805.9, "c": 71231.2}, ...]66```6768### Orders JSON format69```json70[{"price": 73800, "size": 0.00235, "side": "sell"}, ...]71```7273## Customization7475- **Colors**: Dark theme by default. Green/red candles, gold entry, cyan current price, orange limit orders.76- **Zones**: Pass named zones as JSON — they render as shaded regions with labels.77- **Side-aware**: Long positions show entry below current (green PnL arrow), short positions show entry above.78- **Info box**: Auto-generated summary panel with position details, open order count, and zone labels.7980## Notes8182- Works with any exchange data — just needs candles in `{t, o, h, l, c}` format83- Hyperliquid candles from `hl_candles()` use this format natively84- For Orderly/other exchanges, transform to same schema before passing85- The script is self-contained — no network calls, all data passed via args/files
starchild-ai-agent