ETF Rebalancing Automation Guide: Rule-Based Investment Operations

# portfolio_config.yaml
# Last modified: 2026-03-04
# Change reason: 2026 asset allocation adjustment (increased bond allocation)

portfolio:
  name: '2026 Long-Term Growth'
  owner: 'youngjukim'
  base_currency: 'KRW'
  broker: 'Korea Investment & Securities' # or Kiwoom, Mirae Asset, etc.

  # Target asset allocation
  allocation:
    core:
      weight: 0.70
      assets:
        - ticker: 'TIGER US S&P500'
          code: '360750'
          target: 0.35
          min: 0.30
          max: 0.40
        - ticker: 'KODEX 200'
          code: '069500'
          target: 0.15
          min: 0.10
          max: 0.20
        - ticker: 'TIGER US Treasury 10Y Futures'
          code: '305080'
          target: 0.15
          min: 0.10
          max: 0.20
        - ticker: 'KODEX Composite Bond (AA- and above) Active'
          code: '443160'
          target: 0.05
          min: 0.02
          max: 0.08

    satellite:
      weight: 0.30
      assets:
        - ticker: 'TIGER Semiconductor'
          code: '091230'
          target: 0.10
          min: 0.05
          max: 0.15
        - ticker: 'KODEX Secondary Battery Industry'
          code: '305720'
          target: 0.10
          min: 0.05
          max: 0.15
        - ticker: 'TIGER Gold & Silver Futures (H)'
          code: '319640'
          target: 0.10
          min: 0.05
          max: 0.15

  # Rebalancing rules
  rebalancing:
    strategy: 'hybrid'
    scheduled:
      frequency: 'quarterly'
      months: [1, 4, 7, 10] # First business day of Jan, Apr, Jul, Oct
      day: 'first_business_day'
    drift_trigger:
      threshold: 0.05 # Emergency rebalancing when +/-5% deviation
      check_frequency: 'weekly' # Check every Monday
    constraints:
      min_trade_amount: 100000 # Minimum trade amount 100,000 KRW
      avoid_ex_dividend_dates: true # Avoid trading around ex-dividend dates
      tax_loss_harvesting: false # Low effectiveness in Korea

  # Cost settings
  costs:
    etf_commission_rate: 0.00015 # 0.015% (online broker standard)
    etf_tax_rate: 0.0 # Domestic ETF capital gains tax-free (as of 2025)
    overseas_etf_tax_rate: 0.22 # Overseas ETF capital gains tax 22%
    slippage_estimate: 0.001 # 0.1% slippage estimate

"""
ETF Rebalancing Engine
- Reads portfolio config file and calculates the difference between current and target weights
- Generates trade orders for assets that need rebalancing
"""
import yaml
from dataclasses import dataclass
from typing import Optional


@dataclass
class TradeOrder:
    """Trade order data."""
    ticker: str
    code: str
    action: str          # "BUY" or "SELL"
    amount_krw: int      # Trade amount (KRW)
    reason: str          # Rebalancing reason

    def __str__(self):
        return (
            f"[{self.action}] {self.ticker} ({self.code}) "
            f"₩{self.amount_krw:,} - {self.reason}"
        )


def load_config(path: str = "portfolio_config.yaml") -> dict:
    """Load portfolio configuration file."""
    with open(path, "r", encoding="utf-8") as f:
        return yaml.safe_load(f)


def get_current_holdings(broker_api) -> dict:
    """Fetch current holdings from broker API.

    Returns:
        {asset_code: {"value_krw": amount, "quantity": count}}
    """
    # In production, use Korea Investment OpenAPI, Kiwoom Open API+, etc.
    # Returning sample data here
    return {
        "360750": {"value_krw": 4_200_000, "quantity": 250},
        "069500": {"value_krw": 1_600_000, "quantity": 45},
        "305080": {"value_krw": 1_400_000, "quantity": 140},
        "443160": {"value_krw": 500_000, "quantity": 50},
        "091230": {"value_krw": 1_500_000, "quantity": 30},
        "305720": {"value_krw": 800_000, "quantity": 25},
        "319640": {"value_krw": 1_000_000, "quantity": 80},
    }


def calculate_drift(config: dict, holdings: dict) -> list[dict]:
    """Calculate the drift of each asset from its target weight."""
    total_value = sum(h["value_krw"] for h in holdings.values())
    if total_value == 0:
        return []

    results = []
    for section in ["core", "satellite"]:
        for asset in config["portfolio"]["allocation"][section]["assets"]:
            code = asset["code"]
            holding = holdings.get(code, {"value_krw": 0})
            current_weight = holding["value_krw"] / total_value
            target_weight = asset["target"]
            drift = current_weight - target_weight

            results.append({
                "ticker": asset["ticker"],
                "code": code,
                "target_weight": target_weight,
                "current_weight": round(current_weight, 4),
                "drift": round(drift, 4),
                "drift_pct": round(drift * 100, 2),
                "value_krw": holding["value_krw"],
                "section": section,
            })

    return results


def needs_rebalancing(
    drift_data: list[dict],
    threshold: float = 0.05,
) -> bool:
    """Check if any asset exceeds the drift threshold."""
    return any(abs(d["drift"]) > threshold for d in drift_data)


def generate_orders(
    config: dict,
    drift_data: list[dict],
    total_value: int,
    min_trade: int = 100_000,
) -> list[TradeOrder]:
    """Generate the list of trade orders needed for rebalancing."""
    orders = []

    for asset in drift_data:
        target_value = int(total_value * asset["target_weight"])
        diff = target_value - asset["value_krw"]

        # Skip if below minimum trade amount
        if abs(diff) < min_trade:
            continue

        action = "BUY" if diff > 0 else "SELL"
        reason = (
            f"Target {asset['target_weight']*100:.1f}% vs "
            f"Current {asset['current_weight']*100:.1f}% "
            f"(Drift {asset['drift_pct']:+.2f}%p)"
        )

        orders.append(TradeOrder(
            ticker=asset["ticker"],
            code=asset["code"],
            action=action,
            amount_krw=abs(diff),
            reason=reason,
        ))

    return orders


def run_rebalancing(
    config_path: str = "portfolio_config.yaml",
    dry_run: bool = True,
) -> None:
    """Execute the complete rebalancing process."""
    config = load_config(config_path)
    holdings = get_current_holdings(broker_api=None)
    total_value = sum(h["value_krw"] for h in holdings.values())

    print(f"Total assets: ₩{total_value:,}")
    print(f"Rebalancing strategy: {config['portfolio']['rebalancing']['strategy']}")
    print()

    # Calculate drift
    drift_data = calculate_drift(config, holdings)

    print("=== Current Portfolio Drift ===")
    for d in drift_data:
        flag = " ⚠" if abs(d["drift"]) > 0.05 else ""
        print(
            f"  {d['ticker']}: "
            f"Target {d['target_weight']*100:.1f}% | "
            f"Current {d['current_weight']*100:.1f}% | "
            f"Drift {d['drift_pct']:+.2f}%p{flag}"
        )
    print()

    # Determine if rebalancing is needed
    threshold = config["portfolio"]["rebalancing"]["drift_trigger"]["threshold"]
    if not needs_rebalancing(drift_data, threshold):
        print("Rebalancing not needed: All assets are within threshold")
        return

    # Generate trade orders
    min_trade = config["portfolio"]["rebalancing"]["constraints"]["min_trade_amount"]
    orders = generate_orders(config, drift_data, total_value, min_trade)

    print(f"=== Trade Orders ({len(orders)} orders) ===")
    for order in orders:
        print(f"  {order}")
    print()

    # Cost estimate
    commission_rate = config["portfolio"]["costs"]["etf_commission_rate"]
    total_trade = sum(o.amount_krw for o in orders)
    estimated_cost = int(total_trade * commission_rate)
    print(f"Total trade amount: ₩{total_trade:,}")
    print(f"Estimated commission: ₩{estimated_cost:,}")

    if dry_run:
        print("\n[DRY RUN] No actual orders were executed.")
    else:
        print("\n[LIVE] Executing orders...")
        # In production, call broker API


if __name__ == "__main__":
    run_rebalancing(dry_run=True)

Total assets: ₩11,000,000
Rebalancing strategy: hybrid

=== Current Portfolio Drift ===
  TIGER US S&P500: Target 35.0% | Current 38.2% | Drift +3.18%p
  KODEX 200: Target 15.0% | Current 14.5% | Drift -0.45%p
  TIGER US Treasury 10Y Futures: Target 15.0% | Current 12.7% | Drift -2.27%p
  KODEX Composite Bond (AA- and above) Active: Target 5.0% | Current 4.5% | Drift -0.45%p
  TIGER Semiconductor: Target 10.0% | Current 13.6% | Drift +3.64%p
  KODEX Secondary Battery Industry: Target 10.0% | Current 7.3% | Drift -2.73%p
  TIGER Gold & Silver Futures (H): Target 10.0% | Current 9.1% | Drift -0.91%p

=== Trade Orders (4 orders) ===
  [SELL] TIGER US S&P500 (360750) ₩350,000 - Target 35.0% vs Current 38.2% (Drift +3.18%p)
  [BUY] TIGER US Treasury 10Y Futures (305080) ₩250,000 - Target 15.0% vs Current 12.7% (Drift -2.27%p)
  [SELL] TIGER Semiconductor (091230) ₩400,000 - Target 10.0% vs Current 13.6% (Drift +3.64%p)
  [BUY] KODEX Secondary Battery Industry (305720) ₩300,000 - Target 10.0% vs Current 7.3% (Drift -2.73%p)

Total trade amount: ₩1,300,000
Estimated commission: ₩195

[DRY RUN] No actual orders were executed.

# .github/workflows/rebalance-check.yml
name: ETF Rebalancing Check

on:
  schedule:
    # Every Monday at 09:00 KST (00:00 UTC)
    - cron: '0 0 * * 1'
  workflow_dispatch: # Manual execution

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install pyyaml requests

      - name: Rebalancing check (Dry Run)
        run: python rebalance.py --dry-run
        env:
          BROKER_APP_KEY: ${{ secrets.BROKER_APP_KEY }}
          BROKER_APP_SECRET: ${{ secrets.BROKER_APP_SECRET }}

      - name: Send notification (Slack)
        if: always()
        run: |
          python notify.py --channel "#investment" \
            --message "Weekly rebalancing check complete. See GitHub Actions logs for details."
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

"""Send rebalancing check results to Slack."""
import json
import os
import urllib.request


def send_slack_notification(
    webhook_url: str,
    channel: str,
    message: str,
    orders: list[dict] | None = None,
) -> None:
    """Send notification via Slack Incoming Webhook."""
    blocks = [
        {
            "type": "header",
            "text": {
                "type": "plain_text",
                "text": "ETF Rebalancing Check Results",
            },
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": message,
            },
        },
    ]

    if orders:
        order_text = "\n".join(
            f"- {'Buy' if o['action'] == 'BUY' else 'Sell'} "
            f"{o['ticker']} ₩{o['amount']:,}"
            for o in orders
        )
        blocks.append({
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": f"*Required Trade Orders:*\n{order_text}",
            },
        })

    payload = json.dumps({
        "channel": channel,
        "blocks": blocks,
    }).encode("utf-8")

    req = urllib.request.Request(
        webhook_url,
        data=payload,
        headers={"Content-Type": "application/json"},
    )
    urllib.request.urlopen(req)


if __name__ == "__main__":
    send_slack_notification(
        webhook_url=os.environ["SLACK_WEBHOOK_URL"],
        channel="#investment",
        message="All assets are within +/-5% of target weights. No rebalancing needed.",
    )

"""Manage rebalancing trade logs as JSON files."""
import json
from datetime import datetime
from dataclasses import dataclass, asdict


@dataclass
class RebalanceLog:
    """Rebalancing execution record."""
    date: str
    trigger: str  # "scheduled" | "drift" | "manual"
    total_portfolio_value: int
    trades: list[dict]
    total_trade_amount: int
    total_commission: int
    pre_drift: dict   # Drift before rebalancing
    post_drift: dict  # Drift after rebalancing
    notes: str = ""


def save_log(log: RebalanceLog, path: str = "rebalance_log.json"):
    """Append trade log to file."""
    try:
        with open(path, "r") as f:
            logs = json.load(f)
    except FileNotFoundError:
        logs = []

    logs.append(asdict(log))

    with open(path, "w", encoding="utf-8") as f:
        json.dump(logs, f, indent=2, ensure_ascii=False)


# Usage example
log = RebalanceLog(
    date="2026-03-04",
    trigger="scheduled",
    total_portfolio_value=11_000_000,
    trades=[
        {"ticker": "TIGER US S&P500", "action": "SELL", "amount": 350_000},
        {"ticker": "TIGER US Treasury 10Y Futures", "action": "BUY", "amount": 250_000},
    ],
    total_trade_amount=600_000,
    total_commission=90,
    pre_drift={"TIGER US S&P500": 3.18, "TIGER US Treasury 10Y Futures": -2.27},
    post_drift={"TIGER US S&P500": 0.12, "TIGER US Treasury 10Y Futures": -0.08},
    notes="2026 Q1 scheduled rebalancing. S&P500 overweight transferred to bonds.",
)
save_log(log)