Folio Skill

Folio 是一套自架的投資追蹤系統，提供股票觀察名單管理、三層漏斗掃描、護城河分析、價格警報、外匯換匯時機監控、以及 Telegram 通知。

Prerequisites

• •Folio 的 Docker Compose 服務正在運行
• •Backend API 預設在 http://localhost:8000
• •(Optional) Set FOLIO_API_KEY environment variable for production security

Authentication

Folio supports optional API key authentication via the X-API-Key header.

Dev Mode (default): If FOLIO_API_KEY is unset, authentication is disabled.

Production Mode: Set FOLIO_API_KEY in .env and include it in all requests:

# Generate API key
make generate-key

# Add to .env
echo "FOLIO_API_KEY=your-key-here" >> .env

# Export for shell commands
export FOLIO_API_KEY="your-key-here"

All curl commands below assume you'll add -H "X-API-Key: $FOLIO_API_KEY" when auth is enabled.

Quick Start

查看投資組合摘要

curl -s http://localhost:8000/summary \
  -H "X-API-Key: $FOLIO_API_KEY"

透過 Webhook 執行操作

curl -s -X POST http://localhost:8000/webhook \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $FOLIO_API_KEY" \
  -d '{"action": "summary"}'

Webhook Actions

POST /webhook 是統一入口，接受 JSON body：

{
  "action": "string",
  "ticker": "string (optional)",
  "params": {}
}

Supported Actions

Tip: Use help first to discover all supported actions and their parameters at runtime.

add_stock Example

{
  "action": "add_stock",
  "params": {
    "ticker": "AMD",
    "category": "Moat",
    "thesis": "ASIC 與 AI GPU 的強力競爭者",
    "tags": ["AI", "Semiconductor"]
  }
}

withdraw Example

{
  "action": "withdraw",
  "params": {
    "amount": 50000,
    "currency": "TWD"
  }
}

Returns a prioritized sell plan: (1) overweight rebalancing, (2) tax-loss harvesting, (3) liquidity order. Each recommendation includes ticker, quantity, sell value, reason, and unrealized P/L.

fx_watch Example

{
  "action": "fx_watch"
}

Analyzes all active FX watch configurations and sends Telegram alerts for currency pairs meeting alert conditions (near recent high or consecutive increases). Response includes total_watches, triggered_alerts, and sent_alerts counts. Subject to cooldown mechanism — same config won't re-alert within its reminder_interval_hours.

Response Format

All webhook responses follow this structure:

{
  "success": true,
  "message": "Human-readable result",
  "data": {}
}

Error Response Format

Direct API endpoints return structured errors with a machine-readable error_code:

{
  "detail": {
    "error_code": "STOCK_NOT_FOUND",
    "detail": "找不到股票 NVDA。"
  }
}

Use error_code for programmatic branching instead of parsing the human-readable detail string.

Common error codes: STOCK_NOT_FOUND, STOCK_ALREADY_EXISTS, STOCK_ALREADY_INACTIVE, STOCK_ALREADY_ACTIVE, CATEGORY_UNCHANGED, HOLDING_NOT_FOUND, PROFILE_NOT_FOUND, SCAN_IN_PROGRESS, TELEGRAM_NOT_CONFIGURED, PREFERENCES_UPDATE_FAILED.

Direct API Endpoints

For advanced use, you can call individual endpoints directly:

Categories

Daily Change Tracking (New)

The following endpoints now include daily change fields calculated from yfinance historical data (previous trading day close vs. current close):

GET /ticker/{ticker}/signals — Response Fields

GET /rebalance — Response Fields (New)

Edge Cases:

• •previous_close and change_pct will be null for newly added stocks with insufficient history (< 2 days)
• •Weekend/holiday gaps are automatically handled by yfinance (uses last trading day)
• •Cash holdings have no price change (same current and previous value)

Usage Tips

• •Use fear_greed to check market sentiment via VIX + CNN Fear & Greed Index before making buy/sell decisions ("be greedy when others are fearful")
• •Use summary first to get an overview before drilling into individual stocks
• •Use signals to check if a stock is oversold (RSI < 30) or overheated (Bias > 20%)
• •Use moat to verify if a stock's fundamentals (gross margin) are still intact
• •Use scan to trigger a full portfolio analysis with Telegram notifications
• •Use rebalance to check if portfolio allocation drifts from target. The response includes an xray array showing true exposure per stock (direct + indirect via ETFs)
• •Add ?display_currency=TWD to /rebalance to see all values in TWD (supports USD, TWD, JPY, EUR, GBP, CNY, HKD, SGD, THB)
• •Use POST /rebalance/xray-alert to trigger Telegram warnings for stocks whose true exposure (direct + ETF indirect) exceeds 15%
• •When adding holdings, set currency field to match the holding's native currency (e.g., "TWD" for Taiwan stocks, "JPY" for Japan stocks)
• •Use GET /currency-exposure to check currency concentration risk; response includes cash_breakdown (cash-only), breakdown (full portfolio), and fx_rate_alerts (three-tier rate-change alerts) for separate analysis
• •Use POST /currency-exposure/alert to trigger Telegram alerts for three-tier FX rate changes (daily spike >1.5%, 5-day swing >2%, 3-month trend >8%), alerts include cash exposure amounts
• •Use POST /fx-watch to set up FX timing monitors — supports 9 currencies (USD, TWD, JPY, EUR, GBP, CNY, HKD, SGD, THB) in any pair combination
• •Use POST /fx-watch/check to analyze all active monitors without sending notifications — good for quick market checks
• •Use POST /fx-watch/alert to trigger Telegram alerts for FX timing opportunities (near recent high or consecutive increases); subject to cooldown (reminder_interval_hours)
• •Use PATCH /fx-watch/{id} with {"is_active": false} to temporarily pause a monitor without deleting it
• •Use withdraw when you need cash — tell it the amount and currency (e.g., {"amount": 50000, "currency": "TWD"}), it will recommend which holdings to sell using a 3-tier priority: overweight rebalancing, tax-loss harvesting, then liquidity order
• •Use GET /stress-test?scenario_drop_pct=-20&display_currency=USD to simulate portfolio stress under market crash scenarios (-50% to 0%). Response includes portfolio Beta, expected loss amount/percentage, pain level classification, per-holding breakdown with Beta values, and advice for high-risk portfolios. Supports multi-currency display (USD, TWD, JPY, EUR, GBP, CNY, HKD, SGD, THB)
• •Use make backup before any destructive operation (e.g., docker compose down -v)
• •When users report errors after an upgrade, check docker compose logs backend --tail 50 first

Service Operations

Use exec tool to run these commands from the Folio project root for infrastructure management.

Backup & Restore

• •make backup — Backup database (timestamped file in ./backups/)
• •make restore — Restore from latest backup
• •make restore FILE=backups/radar-YYYYMMDD.db — Restore specific backup

Upgrade & Restart

• •docker compose up --build -d — Safe rebuild (entrypoint handles volume permissions automatically)
• •docker compose down -v — Full reset, DELETES ALL DATA (suggest make backup first)

Health & Diagnostics

• •curl -sf http://localhost:8000/health — Backend health check
• •docker compose ps — Container status
• •docker compose logs backend --tail 50 — Recent backend logs