ATH 回撤不是折扣標籤：先重建歷史高點的來源

一張卡片寫「距 ATH 下降某個百分比」，看來只是兩個數字的減法。但在動手算之前，必須知道高點是哪家 provider 依哪組 ticker、哪種 quote currency 和哪段 history coverage 建立，也必須知道 current price 是同一方法在什麼時間的值。少了這些欄位，百分比可以很精確，比較對象卻是拼湊的。

回撤只是一筆來源化歷史比較。它告訴讀者，同一方法的當前觀察與該方法所記歷史高點相差多少；它不說明資產是否低估、會不會回到高點，也不是未來報酬轉譯器。把方法來源補齊，才能將一個引人聯想的數字改寫成可複核的歷史紀錄。

算式之前先建立歷史證據包

歷史證據包的第一組欄位是 provider、asset ID、quote currency 和 ticker set。provider 決定使用哪些輸入及如何處理異常；asset ID 避免同代號或遷移前後資料靜默併合；quote currency 說明高點用什麼單位計價；ticker set 說明哪些市場觀察進入計算。

第二組是 history coverage：收錄起點、結束點、回傳粒度、缺口和修訂版本。如果供應商從資產成交多年後才開始收錄，它的「全時段」是全收錄期，不必然是資產存在的所有時間。某段資料被清理或重建，高點也可能在方法版本中更新。

第三組才是 `ath`、`ath_date`、`current_price`、`last_updated` 與資料狀態。CoinGecko 的 coins markets 文件把這些列為 provider fields，並允許欄位可為空。一筆 `null` 不能改寫成零，也不表示資產沒有曾經出現過高點；它只說明這次方法回傳沒有可用值。

證據包還要留下欄位之間的時間關係。`ath_date` 是供應商記錄高點所屬的時間，`last_updated` 是當前資料的更新線索，本站取得時間則只記錄何時讀到回應。三者不能互相替代。若缺少其中一項，就明確標示該時間未知，不從另一欄複製一個看來完整的日期。

正值 drop convention 要與負號顯示分開

CoinGecko 公開方法把高點跌幅寫為 `(ATH Price - Current Price) / ATH Price × 100%`。當 current price 低於 ATH，這種 drop convention 得到正值，例如「距高點下降 35%」。另一個畫面若以 current price 相對 ATH 的 change convention 顯示，可能寫成 `-35%`。絕對幅度一樣，符號語意卻不同。

一筆紀錄要直接寫清「正值代表距高點的下降幅度」，或「負值代表相對變動」。不能把一家的 `ath_change_percentage` 負號值與另一家的正值 drop 直接相減，也不能在沒有符號說明時將「越大」解讀成同一方向。

公式還隱含一個必要條件：ATH 必須是有效且非零的同單位價格。算術能完成除法，不代表輸入已具備可比較性。若高點為零、缺值、不同貨幣，或來自另一個資產版本，就不應輸出百分比；正確結果是輸入條件未成立。

高點與現價必須來自同一歷史定義

高點、現價、報價貨幣、資產版本與歷史覆蓋必須屬同一供應商方法，才可使用該供應商公布的回撤欄位。另一來源若有不同收錄起點、市場名單或匯率路徑，就保留為獨立紀錄，不把兩端拼成一家供應商未曾發布的數字。

為了讓結果可重查，紀錄還要保存未四捨五入的原始輸入、顯示精度與運算順序。頁面只有縮寫值時，只能核對顯示結果，不能聲稱重建供應商的完整精度。

all-time high 不是圖表視窗高點

七日圖表的最高點只是 7d high，三十日視窗的最高點只是 30d high。它們能回答「這段視窗裡的最高觀察」，不能在沒有更長歷史時自動更名為 all-time high。反過來，provider 的 ATH 欄位也不必然在短期圖表中看得到。

CoinGecko 的 market chart range 文件以指定 coin ID 與 time range 回傳 price、market cap 與 24h volume 歷史序列，時間粒度會依範圍或參數形成。因此，從圖表像素挑出的最高點，還受查詢起訖、授權範圍與取樣粒度影響。要和 ATH 比較，先確認兩者是否屬於同一歷史定義。

視窗還可能不含完整的起訖邊界，或因取樣間隔沒有保留短暫尖峰。即使圖表上最高像素低於 provider 的 ATH 欄位，也不能僅憑肉眼判定其中一方錯誤。應先保存查詢參數、時區、粒度與回傳點，再確認 ATH 是否來自更細或更長的歷史資料。

歷史粒度與收錄起點會改變可見高點

粗粒度資料可能用某段期間的代表值，細粒度資料則保留更多短暫波動。如果高點只出現在很短的區間，不同取樣或聚合方法可能保留不同值。這不能只用「某家錯了」解釋；先檢查 raw observations、聚合粒度和高點欄位的定義。

收錄起點同樣重要。一家 provider 若缺少早期市場，它的最高記錄只是已覆蓋期間的結果。另一家若使用不同市場或報價幣，就算起始日相同，高點也未必相等。所以 ATH 卡片需要來源和範圍，不只是一個大數字。

遷移、面額調整與異常清理需要版本紀錄

資產可能經過合約遷移、鏈別轉換或 redenomination。這些事件可能改變單位數量與價格尺度，卻不能在沒有轉換記錄時將前後數列直接接起來。如果只把面額調整後的數字看成價格暴漲或暴跌，歷史高點就會失去單位一致性。

異常 ticker 也可能讓圖表或 ATH／ATL 出現錯誤。CoinGecko 的圖表錯誤回報文件要求 exact affected range 與 root cause，說明修正是有時間範圍與原因的程序。這不是宣告任何真實資產資料有誤的根據，只提醒研究者保存取得日、版本與異常處理紀錄。

回報異常前，可先把可見現象與原因分開。現象可以是某時間範圍出現不連續、單位跳變或與原始市場紀錄不一致；原因則可能涉及 ticker 映射、面額調整、換算或清理規則。沒有根因證據時，只提交受影響範圍與可重現步驟，不替供應商預先下結論。

任一輸入缺失時答案就是 unknown

如果 `ath`、`ath_date`、`current_price` 或 `last_updated` 其中一欄為 `null`，就無法建立同方法、同貨幣、有時間的完整回撤記錄。正確結果是 unknown，不是百分之零，也不是從另一家 provider 拿一個同名欄位填進來。計算不應比證據更完整。

數據過時或取得失敗也要另存狀態。上一筆成功資料可以作為已標示的歷史快照，卻不是當前值。當前價已不可用時，不繼續顯示一個看來還在更新的回撤百分比。

對於已過時但仍被保存的快照，紀錄應同時展示 value time、fetch time 與 stale 狀態。這能讓讀者知道百分比最後在哪個有效觀察上成立，也能避免把舊值誤認為零變動。當新的同方法資料恢復後，再以新時間建立另一筆紀錄，不覆寫舊快照的來源與狀態。

回撤不能推導目標價或未來報酬

距高點很遠，可能來自市場狀態、供應結構、流動性、代幣身分變更或早期異常高點。一個百分比沒有分辨這些原因，也沒有提供回到歷史高點的機制。高點是過去的 provider observation，不是未來應達位置。

同理，回撤較小也不表示狀態較好。它可能只是歷史較短，或供應商所記高點剛出現不久。讀者能從回撤得到的穩健答案只有「按這個來源與方法，目前觀察和記錄高點相差多少」。

一份可重現的歷史紀錄檢核單

1. 記下 provider、asset ID、quote currency、ticker set 與 method version。
2. 記下 history coverage、收錄起點、查詢範圍、粒度與已知清理。
3. 保存 `ath`、`ath_date`、`current_price`、`last_updated` 與每欄狀態。
4. 只在同 provider、method 和 currency 內計算，標明正值 drop 或負號 change convention。
5. 分開 all-time high、7d high、30d high 與 chart-window high，不以視窗代替全收錄期。
6. 若涉及 migration、redenomination 或 anomaly cleanup，保存受影響範圍與版本；沒有證據就留待查。
7. 任一必要輸入為 `null`、missing、stale 或 failed，就輸出 unknown，不以零或另一範圍資料填補。

這份檢核單保存的是一筆歷史比較如何被建立，不對資產未來作評分。下次 provider 修訂歷史或方法時，研究者可以比對是哪一欄改變，而不是只看到百分比跳動就替它編造市場故事。