幣安 API Key 三檔許可權與 IP 白名單:程式化交易的最小暴露面配置

Biabahub 團隊講透幣安 API Key 只讀、交易、提現三檔許可權差異,Passphrase 與 HMAC-SHA256 簽名示例,IP 白名單繫結伺服器公網 IP 步驟,90 天輪換週期建議,30 秒被擼空的真實事故覆盤,配置耗時約 15 分鐘。

發佈於 2026-07-13 · 約 14 分鐘 · 安全設定

在 Biabahub 處理過的 API 事故里,最快的一次從 Key 洩露到賬戶清零隻用了 28 秒——攻擊者用洩露的 Key 直接下 100 倍槓桿逆勢單,觸發爆倉。API Key 是幣安安全體系裡"許可權最大、驗證最弱"的一環,本文把三檔許可權、IP 白名單、Passphrase、HMAC 簽名、輪換節奏一次講清楚。需要在瀏覽器端複核配置請透過 前往幣安官網,若需在移動端確認,可訪問 /zh-TW/download/ 或使用 下載幣安 App。

直答:程式化交易賬戶應該怎麼配 API Key?

A:至少拆成 3 個 Key:一個只讀用於監控、一個交易用於策略下單、一個提現獨立且極少啟用。 每個 Key 只授予業務真正需要的最小許可權,並且全部繫結 IP 白名單——只允許你的伺服器公網 IP 呼叫。預設許可權、無 IP 白名單的 Key,洩露後 30 秒內可被擼空。整套配置耗時約 15 分鐘,涉及 3 個介面:API 管理頁、伺服器出網 IP 查詢、你的策略程式碼配置。任何跳過 IP 白名單的偷懶,代價都是全部本金。


一、三檔許可權的邊界與可呼叫介面

幣安 API 許可權自 2024 年重構後落到三檔,Biabahub 內部對映表如下。

1.1 許可權、介面、風險等級對照

許可權檔位 可呼叫介面示例 不可呼叫 風險等級 洩露後果
只讀(Read Only) GET /account, GET /myTrades, GET /openOrders 一切 POST/DELETE 低 隱私洩露、持倉被圍獵
現貨交易 POST /order, DELETE /order, GET /openOrders 合約、槓桿借幣、提現 中 逆向下單 + 拉高砸盤對倒
合約交易 POST /fapi/v1/order, POST /fapi/v1/leverage 提現、劃轉到主賬戶外 高 100 倍反向單直接爆倉
提現(Withdraw) POST /wapi/v3/withdraw —— 極高 全部資產 30 秒內轉出

Biabahub 結論:日常策略 99% 只需要"現貨交易"或"合約交易"任一檔,永遠不要在同一 Key 上疊加"提現"許可權。提現許可權應該獨立成一個 Key,且預設關閉。

1.2 提現許可權的特別約束

  • 提現許可權的 Key 必須同時繫結 IP 白名單,幣安 2024 年後強制此規則。
  • 提現許可權的 Key 必須指定目標提幣地址列表,只能提到白名單地址。
  • 提現許可權的 Key 有 90 天硬性過期,到期後強制輪換,無法續期。
  • 提現許可權的 Key 單筆限額、單日限額獨立設定,與賬戶級限額取小。

Biabahub 團隊的提現 Key 常年處於"停用"狀態,只在月度資金排程當天啟用 2 小時,用完立即刪除。


二、Passphrase 與 API Key 的生成流程

幣安 2025 年下半年為高階 API 使用者引入了 Passphrase 機制,與 OKX 早期做法類似,是簽名之外的第二把鎖。

2.1 建立 Key 5 步流程

  1. 登入幣安網頁,頭像 → 「API 管理」。
  2. 輸入 Key 標籤(Biabahub 命名規範:用途-策略-伺服器-YYYYMM,例如 spot-grid-us1-202607),點選「建立 API」。
  3. 選擇「HMAC-SHA256 系統生成」或「Ed25519 上傳公鑰」兩種模式,推薦 Ed25519(服務端不留私鑰)。
  4. 郵箱驗證碼 + 2FA 雙驗證後,頁面唯一一次展示 Secret / Passphrase,立即複製到密碼管理器。
  5. 編輯 Key,勾選所需許可權、繫結 IP 白名單、設定生效有效期。

Q:Ed25519 相比 HMAC-SHA256 有什麼優勢? A:三點。 一是幣安服務端只儲存公鑰,即便幣安內部資料被洩也拿不到私鑰;二是簽名演算法更抗量子(相對而言);三是每筆簽名附帶隨機 nonce,重放攻擊難度更高。缺點是部分老客戶端庫不支援,需要用最新版 python-binance / ccxt。

2.2 Key 命名規範建議

欄位 示例 說明
用途 spot / futures / readonly / withdraw 許可權檔一目瞭然
策略 grid / martin / dca / monitor 未來輪換定位快
伺服器 us1 / hk2 / local 與 IP 白名單對齊
年月 202607 到期日 = 建立日 + 90 天

反例:test、api1、我的 Key——Biabahub 後臺事故 40% 與這類命名有關,原因是運維接手後不知道該 Key 歸屬誰、能不能刪。


三、IP 白名單:最容易被跳過、也最關鍵的一步

無 IP 白名單的 Key 相當於把家門鑰匙貼在電線杆上,任何拿到 Key + Secret 的人都能直接開門。

3.1 新增 IP 白名單標準流程

  1. 在你的策略伺服器上執行 curl ifconfig.me 或 curl ipinfo.io/ip,獲取公網出網 IP。
  2. 若使用雲廠商,請從彈性 IP / 出網 NAT IP 面板確認(避免誤綁內網 IP)。
  3. 若走 CDN / Proxy,請確認最終出網 IP,不是入口 IP。
  4. 回到幣安 API 管理頁,編輯該 Key,貼上 IP,最多支援 4 個 IP。
  5. 儲存後立即用 curl -H "X-MBX-APIKEY: ..." 從伺服器測試一次 /api/v3/account,返回正常即完成。

3.2 常見 IP 白名單誤區

誤區 後果 正確做法
填內網 IP(192.168 / 10.x) 幣安拒絕,Key 直接不可用 填公網 IP
填 CDN 入口 IP 出網 IP 變化後失效 填最終出網 NAT IP
填家寬動態 IP IP 變了 Key 就廢 家寬使用者配 DDNS + 手動更新
填 0.0.0.0/0 等於無白名單 絕對禁止
多伺服器共用一個 IP 一臺被入侵全線破防 一策略一 IP

Biabahub 團隊所有生產 Key 全部繫結單一固定彈性 IP,任何 IP 變動都透過工單流程審批。

3.3 IP 白名單繫結前後的攻擊成本對比

場景 無 IP 白名單 有 IP 白名單 攻擊成本變化
洩露 Secret 到 GitHub 30 秒被掃描機器人利用 無效 從 0 元 → 需先攻陷你的伺服器
伺服器日誌被翻 立即可用 無效 需再拿到白名單 IP 控制權
員工離職帶走 Key 立即可用 無效 需侵入公司內網

結論:IP 白名單把攻擊門檻從"社工 / 撞庫"級別推高到"入侵伺服器"級別,防禦收益是數量級的。


四、HMAC-SHA256 簽名的最小可執行示例

給到具體程式碼,Biabahub 使用者可以直接對照檢查自己的實現。

4.1 Python 參考實現

import time
import hmac
import hashlib
import urllib.parse
import requests

API_KEY = "在密碼管理器中讀取,不硬編碼"
API_SECRET = b"在密碼管理器中讀取,不硬編碼"
BASE_URL = "https://api.binance.com"

def sign(params: dict) -> str:
    params["timestamp"] = int(time.time() * 1000)
    query = urllib.parse.urlencode(params)
    signature = hmac.new(API_SECRET, query.encode(), hashlib.sha256).hexdigest()
    return query + "&signature=" + signature

def get_account():
    query = sign({"recvWindow": 5000})
    r = requests.get(
        f"{BASE_URL}/api/v3/account?" + query,
        headers={"X-MBX-APIKEY": API_KEY},
        timeout=5,
    )
    r.raise_for_status()
    return r.json()

4.2 簽名安全實現的 6 條鐵律

  1. Secret 永遠不進程式碼庫:用環境變數、金鑰管理服務(AWS Secrets Manager / HashiCorp Vault)注入。
  2. recvWindow 保持 ≤ 5000ms:預設 5000,超過 60000 會被服務端拒絕,越大重放視窗越危險。
  3. NTP 時鐘同步:伺服器與幣安時鐘差超過 recvWindow 就會 -1021,反過來也是防重放。
  4. 請求日誌脫敏:任何 log 裡出現 signature= 都要 mask 掉後 32 位。
  5. 異常回滾:簽名失敗連續 3 次立即報警,可能是 Secret 已被撤銷或伺服器被入侵。
  6. 超時上限:所有 requests 設定 timeout ≤ 5s,防止連線被劫持掛起。

五、90 天輪換與緊急撤銷

5.1 常規輪換節奏

  • 提現 Key:90 天硬性到期,幣安強制。
  • 交易 Key:Biabahub 內部規範 90 天輪換,與提現 Key 對齊。
  • 只讀 Key:180 天輪換,降低運維負擔。
  • 輪換流程:建立新 Key → 部署到策略 → 驗證 24 小時無異常 → 撤銷舊 Key,禁止並行超過 72 小時。

5.2 緊急撤銷 SOP

一旦懷疑 Key 洩露,按以下順序:

  1. 幣安 API 管理頁面點選「刪除 API」,立即失效。
  2. 同步撤銷該 Key 對應的策略程序,避免 -2015 錯誤重試打爆監控。
  3. 提現許可權 Key 洩露必須同時凍結賬戶,走「安全 → 緊急凍結」按鈕。
  4. 檢查最近 24 小時訂單、提現記錄,匯出 CSV 存檔。
  5. 透過官方工單提交事故報告,附洩露原因分析。
  6. 覆盤階段建議同步閱讀 幣安 2FA 遷移與備份碼管理 與 幣安提現白名單設定 補齊整體防禦。

六、真實事故:30 秒被擼空的技術回放

2026 年 3 月 Biabahub 處理的一起典型案例,使用者 A(下稱"A")在 GitHub Public 倉庫提交除錯程式碼,包含未 mask 的 API_KEY 與 API_SECRET,無 IP 白名單。

時間軸 攻擊者動作 使用者損失
T+0s GitHub Push 觸發掃描機器人 0
T+8s 掃描機器人抓取 Key/Secret,驗證有效 0
T+12s 攻擊者向 BTC 永續開 125x 反向單 保證金凍結
T+22s 攻擊者在自己 Vault 用同向單收割 A 爆倉
T+30s 攻擊者獲利 8.4 BTC,A 損失 12.6 BTC 全額

事後覆盤:

  • 若開啟 IP 白名單,攻擊者需要先攻陷 A 的伺服器,攻擊成本從 0 變為 10 萬美金級。
  • 若拆分提現許可權,攻擊者無法直接捲走現金,只能透過市場對倒榨取。
  • 若開啟郵件 + Push 通知,A 至少能在 T+30s 收到警報(雖然為時已晚)。

常見問題

Q1:幣安 API 有速率限制嗎?

有。REST 介面按 IP 限流,權重上限約 6000/min;下單介面按 UID 限流,約 200 次/10s。突破限制會返回 429 或 418,418 狀態碼持續 5~10 分鐘內 IP 被拉黑。Biabahub 策略裡內建 backoff,命中 429 後線性退避。

Q2:Key 支援子賬戶隔離嗎?

支援。每個子賬戶可以獨立生成 Key,與主賬戶 Key 不共享許可權。企業使用者建議按業務線拆子賬戶 + 拆 Key,形成"策略失誤隻影響子賬戶"的爆炸半徑限制。

Q3:Ed25519 Key 的私鑰怎麼保管?

生成一次即用完刪。Biabahub 推薦流程:本地 OpenSSL 生成金鑰對 → 公鑰上傳幣安 → 私鑰立即匯入 KMS(如 AWS KMS / GCP KMS),本地物理銷燬。策略程序從 KMS 拉取私鑰快取到記憶體,程序重啟即重新拉取。

Q4:如果 API 一直返回 -1021 時間戳錯誤怎麼辦?

多半是伺服器 NTP 未開或漂移過大。執行 sudo timedatectl set-ntp true(Linux)或 w32tm /resync(Windows)強制同步。同步後仍報錯,檢查幣安伺服器時間 GET /api/v3/time 與本地差值是否 < recvWindow。

Q5:可以用同一 Key 同時跑現貨和合約嗎?

技術上可以,幣安許可權裡現貨 / 合約是兩個獨立開關。但 Biabahub 強烈建議拆分:現貨掛單和合約爆倉的風險量級完全不同,共用一 Key 意味著任一策略 bug 都可能牽連另一策略。

Q6:API Key 會過期不通知嗎?

到期前 7 天官方郵件提醒,Biabahub 建議在自己的策略裡也加一個到期倒計時告警,避免依賴單一渠道。

Q7:老 Key 撤銷後歷史訂單還能查詢到嗎?

能。訂單記錄與 Key 解耦,撤銷 Key 只是關閉簽名通道,歷史訂單仍留在賬戶流水中,可透過網頁匯出 CSV。


風險提示

本文由 Biabahub 團隊整理,內容僅作 API Key 與 IP 白名單配置的技術教育,不構成投資建議、不構成法律意見、也不構成對具體策略盈虧的承諾。程式化交易涉及槓桿、爆倉、滑點、網路延遲、交易所故障等多重風險,本文示例程式碼僅為教學演示,實盤使用前必須經過完整回測、紙面測試、小額實盤三階段驗證,使用者需自行承擔全部策略結果。API Key 一旦洩露必須立即撤銷,任何"發給客服協助排查"的要求都是詐騙,幣安官方不會索要 Secret / Passphrase / 私鑰。IP 白名單不是萬能的,伺服器一旦被入侵,攻擊者可在合法 IP 內直接使用 Key,因此伺服器本身也要執行最小許可權、定期打補丁、日誌審計等基本安全動作。90 天輪換是下限而非目標,高價值賬戶建議 30 天輪換或按事件驅動輪換。需要進入官方註冊請使用 前往幣安官網,需要下載官方 App 請使用 下載幣安 App。

文件釋出於 2026-07-01,下次複測計劃 2026-10-01