Backup Claude memory files to project repo

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

memory/MEMORY.md

@@ -0,0 +1,8 @@
+# Memory Index
+
+- [user_profile.md](user_profile.md) — User role: crypto trader running Bitfinex bot, communicates in Traditional Chinese
+- [project_trading_bot.md](project_trading_bot.md) — Key architecture: stop-loss sync, sell logic, order sizing, exposure, post-trade refresh, report format
+- [project_cost_basis_sync.md](project_cost_basis_sync.md) — sync_cost_basis.py: order history cost calculation, wallet sync, Bitfinex API quirks
+- [project_cron_timing.md](project_cron_timing.md) — Crontab timing: main.py :01/:06, sync :02/:32, offset from candle close
+- [feedback_trading.md](feedback_trading.md) — User feedback: real-time stop-loss, no exposure limit, cost-basis order sizing
+- [feedback_api_errors.md](feedback_api_errors.md) — Bitfinex 500 error patterns: stale stop IDs, min order size, balance locking, cancel not-found

memory/feedback_api_errors.md

@@ -0,0 +1,19 @@
+---
+name: feedback_api_errors
+description: Bitfinex API 500 error patterns and fixes — stop ID staleness, min order size, balance locking
+type: feedback
+---
+
+1. **止損 ID 過期導致 SELL 失敗**：step 2b 重掛止損後必須更新 `stop_orders_by_sym`，否則 step 10 SELL 時取消的是舊 ID，真正的止損還在鎖餘額。
+   **Why:** ETH SELL 反覆 500 "not enough balance" 因為 available=0（被止損鎖住）。
+   **How to apply:** step 2b 掛新止損後立即更新 `stop_orders_by_sym[sym]`。
+
+2. **小倉位不掛止損**：低於 `MIN_ORDER_AMOUNT` 的殘留持倉（如 XRP 0.017 < 最低 4）不能掛止損，會被交易所拒絕。
+   **Why:** Bitfinex 500 "minimum size for XRPUST is 4"。
+   **How to apply:** `main.py` step 2b 和 `trader.place_stop_loss_order` 都檢查最低量。
+
+3. **報告排除小倉位**：`_build_portfolio_one_liner` 中，amount < MIN_ORDER_AMOUNT 的持倉不計入持倉數和總值。
+   **Why:** 殘留微量幣（如賣出後剩 0.017 XRP）不是真正的持倉。
+
+4. **Cancel "Order not found" 不是錯誤**：訂單可能已被觸發或過期，返回 True 即可。
+   **Why:** 避免 log 噪音和後續邏輯誤判。

memory/feedback_trading.md

@@ -0,0 +1,17 @@
+---
+name: feedback_trading
+description: User feedback on trading bot behavior — stop-loss real-time, no exposure cap, cost-basis sizing
+type: feedback
+---
+
+1. 止損單不要靠本地記憶，靠 real-time 交易所資料。
+   **Why:** 本地狀態容易不同步，用戶可能手動刪單或加倉後狀態過時。
+   **How to apply:** 每次 cron 週期都從交易所拉 active orders 比對。
+
+2. 帳戶餘額可以扣到 0，不設總曝險上限。
+   **Why:** 總曝險限制在持倉有未實現利潤時會誤擋正常買單。
+   **How to apply:** 不加 `check_total_exposure` 檢查。
+
+3. 下單量基準用「USDT 餘額 + 持倉總成本」，不是交易所 USDT 錢包餘額。
+   **Why:** USDT 錢包餘額不含其他幣種持倉，基數太小導致訂單低於最低門檻。
+   **How to apply:** `risk_manager.py` 的 `total_balance` 改用 available + positions cost。

memory/project_cost_basis_sync.md

@@ -0,0 +1,29 @@
+---
+name: cost_basis_sync
+description: sync_cost_basis.py architecture — order history cost calculation, wallet sync, Bitfinex API quirks
+type: project
+---
+
+## sync_cost_basis.py（每30分鐘 cron :02, :32）
+獨立腳本，從 Bitfinex 訂單歷史重算 entry_price，同時從錢包同步 amount 和 USDT 餘額。
+
+**職責分離：**
+- `sync_cost_basis.py`：撈訂單 + 錢包，更新 entry_price / amount / 餘額
+- `main.py`（每5分鐘 :01, :06...）：只撈錢包同步餘額，不重算成本
+
+**Why:** `update_position()` 本地計算的 amount 用 `amount_usdt / price`，跟交易所實際成交量有差異，累積後總值偏差可達 10%+。
+
+## Bitfinex 訂單 API 注意事項
+
+1. **SELL 訂單 status 不一定是 "EXECUTED"**：可能是 `"INSUFFICIENT BALANCE (U1) was: PARTIALLY FILLED @ ..."`。必須同時檢查 `"EXECUTED"` 和 `"PARTIALLY FILLED"`。
+
+2. **排序不可靠**：`/v2/auth/r/orders/{symbol}/hist` 的 `sort` 參數不保證正確排序。必須在 Python 端按 `mts_create`（index 4）手動排序。
+
+3. **實際成交量 = amount_orig - amount_remaining**：`amount_orig`（index 7）是原始下單量，`amount`（index 6）是剩餘量。不能直接用 `amount_orig`。
+
+4. **nonce: small 錯誤**：API 請求間隔太短會觸發。幣種間至少 `time.sleep(1)`。
+
+5. **Bitfinex 不收手續費**：計算出的 amount 應與錢包完全一致（0% deviation）。
+
+## cost_tracking.json
+記錄每個幣種的訂單撈取起始時間（ms）。完全賣出設為 null，重新買入時更新為新的第一筆 BUY 時間。

memory/project_cron_timing.md

@@ -0,0 +1,14 @@
+---
+name: cron_timing
+description: Crontab timing strategy — 30s offset from candle close, avoid collisions between scripts
+type: project
+---
+
+## Crontab 排程
+
+- `main.py`：`*/5 * * * * sleep 30 && ...`（:00:30, :05:30, :10:30...）
+- `sync_cost_basis.py`：`2,32 * * * *`（:02, :32）
+
+**Why:** Bitfinex 5 分鐘 K 線在整點收盤（:00, :05, :10...），延遲 30 秒確保數據到位。sync_cost_basis 在 :02/:32 避免衝突。
+
+**How to apply:** crontab 不支援秒，用 `sleep 30 &&` 實現。修改排程時維持此偏移策略。

memory/project_trading_bot.md

@@ -0,0 +1,34 @@
+---
+name: trading_bot_architecture
+description: Key architecture decisions for the bifitnex-trading-2 bot — stop-loss, sell logic, order sizing, exposure limits
+type: project
+---
+
+## SELL 使用實際持倉量
+SELL 訂單直接用 `sell_amount`（實際持倉量），不經 USDT→amount 反算，避免精度誤差導致殘餘持倉或 Bitfinex 500 錯誤。
+**Why:** 價格變動導致反算數量與實際持倉有誤差，賣超會 500，賣不完留殘餘。
+**How to apply:** `risk_manager.py` SELL 時設定 `signal["sell_amount"]`，`trader.py` SELL 優先用此值並 truncate 到 8 位小數。
+
+## 止損單依賴交易所即時資料
+每次 cron 週期從交易所拉 active orders，比對持倉是否有正確的 EXCHANGE STOP 單，缺少或不匹配就自動補上。不依賴本地 `stop_order_id` 記憶。
+**Why:** 本地記憶容易因 BUY 加倉、手動刪單等情況失準。
+**How to apply:** `main.py` 2b 區塊用 `fetch_active_orders()` + wallet balances 做 backfill。
+
+## 止損/停利閾值
+- 止損: -3% (`STOP_LOSS_PCT = 0.03`)
+- 停利: +5% (`TAKE_PROFIT_PCT = 0.05`)
+
+## 無總曝險上限
+已移除 `check_total_exposure` 檢查，可用餘額可以扣到 0。BUY 只受：(1) 可用 USDT 餘額 (2) 單幣 30% 上限 限制。
+**Why:** 未實現利潤推高持倉市值超過帳戶餘額時，總曝險限制會誤擋正常 BUY。
+
+## 下單基準 = USDT 餘額 + 持倉總成本
+`validate_trade()` 中 `total_balance = available_usdt + Σ(entry_price × amount)`，不用交易所錢包餘額。
+**Why:** 交易所 `total_balance_usdt` 只反映 USDT 錢包，不含其他幣種持倉價值，導致下單量過小被 MIN_ORDER 擋掉。
+**How to apply:** `risk_manager.py` line 111-116。Position limit 也用同一個 total_balance（不再呼叫 `check_position_limit`），避免判斷不一致。
+
+## 交易後刷新錢包
+step 10 交易完成後，若有任何成交（executed 或 tp_closed），重新 `fetch_account_status()` + `sync_with_exchange()` 確保下一筆交易用最新餘額。
+
+## Slack 報告格式
+`_build_portfolio_one_liner` 顯示：總值、總收益%（= 總值/總成本-1）、可用 USDT、持倉筆數。低於 MIN_ORDER_AMOUNT 的殘留倉位不計入。

memory/user_profile.md

@@ -0,0 +1,10 @@
+---
+name: user_profile
+description: User is a crypto trader running an LLM-driven trading bot on Bitfinex, communicates in Traditional Chinese
+type: user
+---
+
+- 使用 Bitfinex 交易所，跑 LLM 驅動的加密貨幣自動交易機器人
+- 以繁體中文溝通
+- 偏好直接、簡潔的回覆
+- 對交易系統的風險管理、止損、持倉管理有深入理解