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 那边的公告也没明确说对散户的处理。所以你切之前，如果需要抓历史数据做税务申报或绩效归因，先自己把数据拉下来备份——这件事不能等切完了再说。

常见问题