Bitget UTA v3 API 遷移 —
你的 webhook 為什麼會突然 401

alert 在 K 棒上準時觸發，webhook 也送出去了。你去看交易所回的 log，看到的是 HTTP 401 或一句「API-key format invalid」。你檢查 key，還沒到期；檢查 IP 白名單，沒有動過。這件事最近在 Bitget 上特別容易發生——它把 API 換成了 UTA v3 這套新架構，你的 webhook 現在打在錯的門上。

這篇文章不談「UTA 有多好」或者「值不值得升級」，這種事你自己看官方文件比較準。這篇只回答一件事：**你的 webhook 為什麼會安靜地開始 401，以及在你被動遷移之前，你手上有哪些選項。**

這件事實際上發生了什麼

Bitget 現在的 API 文件分成兩套，網址前綴也不同：Classic 走 /api-doc/classic/*，UTA 走 /api-doc/uta/*。Classic 那頁自己第一句就寫「We recommend using the Unified Trading Account (UTA)——it consolidates spot, margin, and derivatives into a single account」，並註明 Classic 處於 maintenance mode、只收「essential updates」（查證日期 2026 年 7 月）。

換句話說，官方對這件事的敘述不是「兩套並存」，是「你應該搬過去」。UTA 的 changelog 這幾個月都在補功能——2026-06-16 補齊了 Trading Data APIs、2026-07-30 上線了 institutional rate limit——同一時間 Classic 的變動紀錄幾乎停了。這是「新的主線」跟「舊的維持」該有的樣子。

為什麼 webhook 會「安靜地」壞掉

自動化交易架構最麻煩的錯，是那種沒有提示、只是不再成功的錯。API 遷移是這一類的教科書案例。

平常你檢查交易所的 API 健康度是看兩個東西：連線通不通、成交回報正不正常。遷移那一刻，這兩個檢查都會過——你的 webhook 伺服器連得上 Bitget，只是每次下單都被回 401；TradingView 端顯示 alert 送出成功，因為對 TradingView 來說「HTTP 200 才算成功」，401 也算「送到了」。真正沒發生的事——訂單根本沒進交易所——在你自己的 log 之外看不到。

換句話說，你會在下一次自己盯盤或看報表的時候才發現，這中間可能已經過了幾個小時或幾天。所以這篇不是要嚇你，是要你今天就把「怎麼知道自己被遷了」這件事的訊號建起來。

你怎麼知道自己現在是哪一邊？

三個地方看，任何一個對得上就是那一邊。

• 用你手上的 ACCESS-KEY 打一次 UTA 的 /api/v3/account/assets（或任何 UTA endpoint）。回 200 就代表你的帳戶已經是 UTA 模式；收到 401 或「API-key format invalid」就代表這把 key 還不能打 UTA endpoint。
• 登入網頁版，看帳戶頁面上方是「統一交易帳戶／Unified Trading Account」還是「經典交易帳戶／Classic」。Bitget 現在會用醒目的 badge 標出來。
• 去 API management 頁面看你這把 key 當時勾的權限選項——UTA 的權限名稱是 Unified account trade / Unified account management（各有 read-only 與 read and write 兩檔），Classic 帳戶模式下沒有這兩個選項。

你可以自己決定什麼時候換嗎

到 2026 年 7 月為止，Bitget 對散戶的說法是「推薦」升級，而不是「強制」——網頁版的入口是自己按「升級」按鈕。這是目前觀察到的現狀，不代表官方承諾永遠都會這樣。歷史上大交易所改帳戶結構時，通常會先給人自願期，之後才排強制批次，然後把 Classic 完全下線。Bitget 的 changelog 節奏跟這個劇本吻合。

Broker 與機構的時程比較明確：Broker UTA Upgrade Notice 有寫遷移排程與 UTA API key 不能打 Classic endpoint 的行為變更。散戶如果掛在某個 broker 帳戶或機構帳戶下面，是有可能被上游決定的。

換過去之前這些事要先做

順序有意義，這是實際踩到的先後：

1. 1
   在 subaccount 上先試一次

   Bitget 的主帳戶可以幫 subaccount 開 API Key Management 權限（預設是關的）。用一個小額 subaccount 切到 UTA、開一把 UTA key、把你其中一條 webhook 指過去跑一天，比在主帳戶上直接切安全得多。
2. 2
   把 endpoint、簽名邏輯、參數名稱都對過一遍

   UTA 跟 Classic 的請求路徑不同，query／body 的欄位名也有一些不一樣（例如下單 body 裡 size 改名成 qty）。你的下單函式如果是「直接複製官方範例」寫成的，換 endpoint 那一刻多半要改超過一行。
3. 3
   先開 UTA key、確認能打通，再把 Classic key 從 webhook 拔掉

   不要反過來。拔掉 Classic 之前先讓 UTA 走通一輪，最壞情況你手上還有 Classic 可以繼續跑；反過來的話中間有一段是兩邊都不能下單。
4. 4
   更新監控告警

   如果你的告警邏輯是 hardcode「401 = key 過期」，換成 UTA 之後那條訊息就不再是 key 過期而是 endpoint 打錯。把訊息文字更新，未來自己 debug 才不會被誤導。

官方沒講清楚、我這邊也還沒摸到的地方

Bitget 到目前沒有公開一份「散戶強制遷移的最終時程」。所以「你有多久可以拖」這件事目前只能觀察：看 changelog、看 Broker UTA Upgrade Notice 的更新、看官方 Telegram（t.me/bitgetOpenapi）有沒有新的公告。我們也沒有內部管道，只能跟你一樣讀這幾個來源。

另一件我們自己還沒完全摸到的事：切換到 UTA 之後，Classic 的訂單、成交、資金流水查詢會不會保留一段時間、保留多久？官方文件沒有寫，Broker 那邊的公告也沒明講對散戶的處理。所以你切之前，如果需要抓歷史資料做稅務申報或績效歸因，先自己把資料拉下來備份——這件事不能等切完了再說。

常見問題