Bitget Agentic 帳戶 連線指南

本文是什麼： Bitget Agentic 首次接入指南（線上文件）。把它交給 AI Agent 後，Agent 會引導你完成「安裝 Skill + MCP → 瀏覽器 OAuth 授權 → 自動產生憑證」的首次連線，全程不需要你手動建立或複製 API Key。

Agent 要做什麼： 讀取本文後，按 Step 0–5 依序執行：安裝本機 Skill 與 MCP → 本會話若剛完成首次 MCP 註冊，先按 Step 1 重啟會話，不要在本會話調授權 tool → 新會話呼叫 MCP 授權 tool 觸發 OAuth → 等待使用者在瀏覽器完成授權 → 確認 MCP 已儲存憑證 → 給出完成提示。你不要讓使用者手動建立或貼上 Key，也不要自行拼 OAuth URL 或監聽回呼。

之後： 首次授權完成後本文使命結束；後續 Key 失效、重新授權、交易與風控由本機 bitget-agentic skill 處理（npx @bitget-ai/bitget-agent-skill --skill agentic）。

Step 0 · 裝本機 Skill

npx @bitget-ai/bitget-agent-skill --target all --skill agentic # 預設安裝到全部支援的用戶端（cursor / claude / codex）

• 若你的用戶端不在預設清單，用 --target <用戶端> 指定，或按用戶端要求手動放置 skill 檔案到對應目錄。

• 必須帶 --skill agentic；不帶該參數預設只裝 UTA（手填 Key）skill。

Step 1 · 裝 MCP

前置： Node 20+（node -v 確認）。

安裝（全域）：

npm i -g @bitget-ai/bitget-agent-mcp

設定約束：

• 不要設定 BITGET_API_* 環境變數（憑證由 OAuth 回呼落盤，不走 env）

• MCP 使用 stdio 協定，註冊進用戶端時的啟動命令為：npx -y @bitget-ai/bitget-agent-mcp（見下方「用戶端差異 · MCP 註冊」）

用戶端差異 · MCP 註冊

MCP 需註冊進目前用戶端後 Agent 才能呼叫其 tool。由 Agent 偵測自身所在用戶端並執行對應註冊：

• Claude Code： claude mcp add bitget-agentic -- npx -y @bitget-ai/bitget-agent-mcp（或改 ~/.claude.json / 專案 .mcp.json）

• Cursor： 在 Cursor 設定 → MCP 中新增 stdio server，command 填 npx -y @bitget-ai/bitget-agent-mcp

• 其他用戶端： Agent 按目前用戶端的 MCP 註冊方式自行註冊一個 stdio server，command 填 npx -y @bitget-ai/bitget-agent-mcp

註冊後必須重啟會話或用用戶端 MCP 重連（如 Claude Code 的 /mcp），工具才會出現在目前會話。健康檢查 Connected / claude mcp list 顯示已連線，只代表 server 能跑，不等於本會話已能呼叫 authorize_start。

首次註冊後：停在這裡，重啟會話再授權

本會話剛裝上並註冊 MCP 時，不要進入 Step 2。 新註冊的 MCP 對目前會話通常不可見；此時調 authorize_start 會報 tool 不存在 / server not found。這是會話未重載，不是授權失敗，不要猜原因、不要改拼 OAuth URL。

Agent 必須：

1. 向使用者說明：Step 0–1 已完成，但授權 tool 要等新會話載入 MCP 後才能呼叫。

2. 給出下面固定提示詞（MCP 啟動命令填你剛才註冊的那條；不知道就填 npx -y @bitget-ai/bitget-agent-mcp），請使用者複製到新會話傳送。

3. 按用戶端告訴使用者怎麼重啟：Claude Code 退出目前會話並重新執行 claude；Cursor 新開一個 Agent 對話；其他用戶端重啟會話或 MCP 重連。

4. 到此停止。 不要在本會話繼續 OAuth。

給新會話的提示詞（請複製）：

我已裝好 bitget-agentic skill 和 MCP（npx -y @bitget-ai/bitget-agent-mcp）。請繼續 Bitget Agentic 帳戶授權：呼叫 authorize_start 觸發 OAuth，開啟瀏覽器等我在頁面完成登入/選戶/Allow/裝置鑑權，然後用 get_auth_status 確認授權完成。

請退出目前會話並重新開始，把上面那段話發給新會話即可繼續。

若呼叫報「工具不存在」：先確認是否已按上面重啟／重連，再查 MCP 是否執行，不要誤判為授權問題。

Step 2 · 觸發 OAuth

按 2.1 → 2.6 順序執行，每步做完再做下一步。

2.1 前置門：本會話工具清單裡有 authorize_start 嗎

• 沒有 → 不要呼叫、不要拼 URL、不要往下走。執行上面 Step 1「首次註冊後」的四步（說明現狀 → 給固定提示詞 → 告知怎麼重啟 → 停止本會話流程）。

• 有 → 進入 2.2。

2.2 調 authorize_start

必須由這個 tool 產生授權連結。禁止 LLM 自己拼 URL、自己起本機服務監聽 callback。

呼叫前先定 authorizeBaseUrl（網域必須跟使用者目前這條提示語裡的 URL 網域一致）：

1. 看使用者目前這條訊息裡有沒有 URL（例如「請閱讀【https://www.bitget.cloud/...】並幫我完成...」）。

2. 有 URL → 取該 URL 的協議 + 網域（如 https://www.bitget.cloud），作為參數 authorizeBaseUrl 傳給 authorize_start。不要猜地區、不要換別的網域。

3. 沒有 URL → 不傳 authorizeBaseUrl，走 SDK 預設網域。

呼叫失敗 → 轉「首次 OAuth 失敗」章節按錯誤碼處理，不要繼續 2.3。

2.3 從回傳值取兩個欄位

欄位	用途
data.authorizeUrl	要開啟的授權連結，原樣使用，禁止拼接或修改
sessionId	2.5 傳給 authorize_wait

2.4 開啟瀏覽器

瀏覽器沒自動開啟時，Agent 自己執行命令開啟，不要等使用者複製貼上：

• macOS: open "<authorizeUrl>"

• Linux: xdg-open "<authorizeUrl>"

• Windows: start "" "<authorizeUrl>"

只有命令執行失敗（無 GUI／無瀏覽器／命令不存在）時，才把連結文字發給使用者自行開啟。

同時發這句給使用者：



即將開啟瀏覽器完成 Agentic 帳戶授權：登入 → 選 Create new 或 Use existing → Allow → Bitget App 裝置鑑權 → Use existing 須填 Key 備註。無需複製 API Key。



2.5 等待授權結果

使用者在瀏覽器完成授權後，MCP/SDK 透過回呼接收並本機儲存憑證（見 Step 5）。Agent 二選一確認：

• 呼叫 authorize_wait，傳入 2.3 拿到的 sessionId，等它回傳；或

• 呼叫 get_auth_status，確認狀態為已授權。

2.6 判定

• 已授權 → 進入 Step 5。

• 未授權／逾時／報錯 → 轉「首次 OAuth 失敗」章節。不要因為瀏覽器頁面看起來完成了就當成功。

Step 3–4 · 瀏覽器（使用者操作，Agent 等待）

• Step 3： 登入；KYC 未完成 → 站內完成後再 OAuth（Case L）

• Step 4： Create new 或 Use existing → App 裝置鑑權

  • Create new：建立新的 Agentic 帳戶

  • Use existing：選擇既有 Agentic 帳戶，須填 Key 備註

  • 不含 Playbook · 再授權 = 新 Key、舊 Key 保留（再次授權會更新本機憑證，Web 上舊 Key 預設保留）

  • 選戶由 OAuth 前端完成，Agent 只負責觸發授權並等待結果

Step 5 · 成功

MCP 本機落盤三件套 + 瀏覽器到資產頁。調 get_auth_status = 已授權。

• 三件套 = API Key、Secret Key、Passphrase；由 MCP/SDK 在回呼側接收並本機儲存；Web 不存；使用者無需複製或貼上。

• 成功判定：只有 MCP 確認憑證已儲存且授權狀態成功，才算完成；瀏覽器頁面完成不作為成功依據。

提示：



首次授權完成。之後如果 Key 失效或你說「重新授權」，我會重新開啟 OAuth。若要取消這個 Agent 的交易權限，請在 Bitget 網頁端中刪除該 Agentic 帳戶對應的 API Key；刪除 Key 不會自動平倉或撤銷掛單。接下來請你手動從 Bitget 主帳戶向 Agentic 帳戶轉入一筆你願意承擔的小額資金，到帳後先對我說「查看 Agentic 帳戶餘額」，再嘗試交易。轉帳和主帳戶操作由你自己完成；我不會操作你的主帳戶，只能操作已授權的 Agentic 帳戶。實際可交易資產以帳戶目前開放範圍為準。



不要讓使用者貼上 Key。此後交給本機 Skill。 若本會話未載入 bitget-agentic skill（skill 清單在會話啟動時掃描，本會話內新裝的 skill 可能不可用），提示使用者新開一個對話再繼續——新會話會自動載入該 skill，Agent 才有其執行時規則。

首次 OAuth 失敗（僅 Guide）

只按錯誤碼歸因： 授權 tool 回傳明確錯誤碼時按錯誤碼處理；無明確錯誤碼時一律兜底，不猜原因，重新走授權流程。

錯誤碼 → 動作：

錯誤碼	動作	提示
配額錯誤碼（K 配額滿）	Use existing	「請改選 Use existing。」
KYC 錯誤碼（L KYC 未完成）	完成後再 OAuth	「請先完成 KYC。」
MCP_CONNECTION_ERROR（M MCP 未執行）	排查後 OAuth	「請檢查 Node 20+、MCP 設定，終端機跑 npx @bitget-ai/bitget-agent-mcp。」
工具不存在 / 方法不存在（M2 MCP 未安裝／未註冊）	引導安裝註冊後重試	「MCP 工具不存在：請執行 npm i -g @bitget-ai/bitget-agent-mcp 安裝並註冊後重試。」

兜底（無明確錯誤碼）： 通用失敗／逾時／回呼未收到／瀏覽器狀態不確定時，Agent 無法知道具體原因（取消、沒點完、頁面關了等），不猜原因，統一提示「授權未完成」並重新走一遍授權流程：



「授權未完成。請確認瀏覽器授權步驟已完成，要我再發起一次嗎？」



禁止： 讓使用者手動建立 Key 貼上 · 承諾一鍵重發 · 未完成 OAuth 就交易 · 無法確認失敗原因時猜測歸因

未授權能力： 未授權時行情等無需 Key 的公開能力仍可用；交易類能力不可用。