Exchange Integration · API Migration

Bitget UTA v3 API Migration —
Why Your Webhook Suddenly Starts Returning 401

2026-07-31·10 min read

The alert fired on the candle, right on time. Your webhook was sent. You open the exchange's log and see HTTP 401, or the message "API-key format invalid". You check the key — not expired. You check the IP whitelist — nothing has changed. This has been happening on Bitget lately: they moved their API to a new architecture called UTA v3, and your webhook is now knocking on the wrong door.

This post doesn't argue how good UTA is or whether the upgrade is worth it — the official docs are a better source for that. It answers one thing: **why your webhook starts silently returning 401, and what options you actually have before you get migrated involuntarily.**

TL;DR

Once your account is switched to UTA, any webhook still pointing at the Classic (v2) endpoints gets rejected. Bitget's own Broker UTA Upgrade Notice states it plainly: "API Keys for UTA Unified Trading Accounts cannot access Classic Account API endpoints" (source: bitget.com/support/articles/12560603886018, verified July 2026). So the moment your account mode flips to UTA, if your execution server is still calling the old endpoints, everything falls off at once.

What's Actually Going On

Bitget now publishes two separate API doc sets, with different URL prefixes: Classic sits under /api-doc/classic/*, UTA under /api-doc/uta/*. The Classic landing page opens with "We recommend using the Unified Trading Account (UTA) — it consolidates spot, margin, and derivatives into a single account", and marks Classic as being in maintenance mode, taking "essential updates" only (verified July 2026).

Put differently, the official narrative isn't "two APIs coexisting" — it's "you should move". The UTA changelog has been shipping steadily over the past months (Trading Data APIs added on 2026-06-16, institutional rate limits on 2026-07-30), while Classic's changelog has gone almost silent. That's what "the new mainline" and "the maintained legacy" are supposed to look like.

How Far the Docs Actually Go

The causal chain above — "switching account mode = switching endpoints" — is directly stated in the official docs: Classic and UTA are two distinct APIs, and which one a key is bound to is decided by the account mode. What's not in a single official document is exactly when you personally will be forced to switch. Public notices so far have focused on brokers and institutional accounts. That question gets its own section below.

Why the Webhook Breaks "Silently"

The nastiest bugs in automated trading are the ones with no alarm — the ones where things simply stop succeeding. API migrations are a textbook case.

Your normal API-health checks look at two things: whether the connection works, and whether fill reports come back. At the moment of migration, both of those still pass — your webhook server can still reach Bitget, it just gets 401 on every order; TradingView shows the alert as sent successfully, because for TradingView "HTTP 200 = success" and 401 also counts as "delivered". The thing that actually didn't happen — the order never reached the exchange — is invisible outside your own logs.

Signal	Before migration	At migration
TradingView alert fires	OK	OK
webhook HTTP response	200	401
Order visible in exchange orderbook	Yes	No
Account balance change	Yes	No
Exchange email / app push	Depends on settings	Depends on settings, usually not

What's visible and what's invisible at the moment of migration. Verified July 2026.

Put differently, you find out the next time you actually glance at the chart or the reports — and by then hours or days may have passed. The point of this piece isn't to scare you, it's to convince you to build the "how do I know I got migrated" signal today.

How Do You Tell Which Side You're Currently On?

Three places to look. If any one of them lines up, that's your answer.

Take the ACCESS-KEY you already have and hit UTA's /api/v3/account/assets (or any UTA endpoint). A 200 means your account is already in UTA mode; a 401 or "API-key format invalid" means this key still can't call UTA endpoints.
Log into the web UI and look at the top of the account page — does it say "Unified Trading Account" or "Classic"? Bitget now shows a prominent badge either way.
Go to API management and look at the permission checkboxes on this key. UTA permissions are named Unified account trade / Unified account management (each with read-only and read-and-write variants). Those options don't exist under Classic mode.

A Small Thing Worth Doing Anyway

Route 401 responses from your execution server to **their own dedicated alert**, separate from other 4xx errors. This pays off forever, not just for the Bitget migration: other exchanges change permission rules too, you accidentally revoke a key, a CDN blocks you, clock skew expires your timestamp — all 401, all worth knowing about right away.

Do You Get to Choose When to Switch?

As of July 2026, Bitget's stance for retail is "recommended", not "mandatory" — the web UI shows an "Upgrade" button you can press yourself. That is the current observed state, not a promise about the future. Historically, when large exchanges restructure account architecture they open a voluntary window first, then schedule forced batches, then take the legacy stack down entirely. The tempo of Bitget's changelog fits that script.

For brokers and institutional accounts, the timeline is clearer: the Broker UTA Upgrade Notice spells out the migration schedule and the behavior change where UTA API keys can no longer call Classic endpoints. Retail traders sitting under a broker account or an institutional account may have that decision made for them upstream.

Is your Bitget account a retail account you opened yourself, or does it sit under a broker / institutional account?

Opened it myself (retail) →You currently get to pick your own timing. Run UTA on a test subaccount first, then flip the main account.

Under a broker / institution →Ask your broker: what's the schedule, and will they keep your Classic key alive? You don't get to make this call alone.

How many strategies do you have live-trading right now?

0–1 →Just switch. Blast radius is small, and fixing things on the UTA side goes faster than dragging your feet.

3+ or anything HFT →Run them in parallel first: issue a fresh UTA key, spin up a subaccount in UTA mode, mirror your strategies as shadow orders, and only switch once a week of side-by-side reconciles cleanly against the Classic main account.

Things to Do Before You Switch

The order matters. This is the sequence people actually trip over:

1
Try it on a subaccount first
Your Bitget main account can enable API Key Management for a subaccount (off by default). Take a small-funded subaccount, flip it to UTA, issue a UTA key, point one of your webhooks at it for a day. That's dramatically safer than flipping the main account directly.
2
Diff endpoints, signing logic and parameter names
UTA and Classic use different request paths, and some query / body field names have changed too (e.g., size in the order body is renamed to qty). If your order function was "copy the official example verbatim"-shaped, changing the endpoint is going to require more than a one-line edit.
3
Get a working UTA key first, then remove the Classic key from your webhook
Not the other way around. Prove UTA works end-to-end before you tear out Classic. Worst case, you still have Classic to fall back on; do it in reverse and there's a window where neither one can place orders.
4
Update your monitoring
If your alert logic hardcodes "401 = key expired", after UTA that message no longer means an expired key — it means you called the wrong endpoint. Update the alert text so future-you doesn't get misled at 3 a.m.

What the Docs Don't Spell Out (and We Haven't Fully Nailed Down Either)

Don't Treat This Section as Permanent

The items below have no consolidated official statement as of 2026-07-31 — only fragmented notices. Before actually moving, cross-check the date yourself at bitget.com/api-doc/uta/changelog.

Bitget has not published a "final forced migration schedule for retail". So "how long can I stall" is currently a matter of observation: watch the changelog, watch updates to the Broker UTA Upgrade Notice, watch the official Telegram (t.me/bitgetOpenapi) for new announcements. We don't have an inside channel either — we're reading the same sources you are.

Another thing we haven't fully verified ourselves: after switching to UTA, do Classic's order history, fill history and funding-flow queries stay accessible, and for how long? The docs don't say, and the broker notices don't clearly address retail either. So if you need historical data for tax filing or performance attribution, pull it down and back it up yourself before you switch — this is not something to figure out after the fact.

FAQ

If I'm a TVSBot user still on a Classic key, will you switch it for me automatically?

No. Your key is one you generated in the Bitget web UI and it's stored on your side; we just use it to talk to the exchange. So when — and whether — you switch is your call. On the API keys page in your dashboard you can keep the old and new key side by side and pin specific strategies to either one, which means you don't have to stop the whole account to migrate.

What does UTA actually change for me in practice?

Setting aside capital efficiency, the most concrete difference for webhook users is "one key covers everything" — under a UTA account, spot, USDT-M, USDC-M and Coin-M (advanced mode) all share one endpoint and one signature. Under Classic you had separate permission toggles per product, and it was easy to forget one when writing code. UTA removes that pothole.

If I get migrated without noticing, do my Classic open orders get cancelled?

The docs give no clear answer here. Reasoning from the technical architecture (this is inference, not an official guarantee), since the underlying account is the same and only the account mode has changed, open orders should carry over rather than be wiped — but we haven't reproduced this ourselves. So the first thing to do when you confirm you've been switched is manually check the spot and futures pages to confirm your open orders are still there, rather than trusting anyone's inference — ours included.

Get started

Ready to ship what you just learned?

Point your TradingView strategies at TVSBot — bring your own API key (Classic or UTA both work), dry-run first, and when you switch exchanges you can hold both keys at once and pin them strategy by strategy.

Start free