幣安 API Key 三檔許可權與 IP 白名單:程式化交易的最小暴露面配置
Biabahub 團隊講透幣安 API Key 只讀、交易、提現三檔許可權差異,Passphrase 與 HMAC-SHA256 簽名示例,IP 白名單繫結伺服器公網 IP 步驟,90 天輪換週期建議,30 秒被擼空的真實事故覆盤,配置耗時約 15 分鐘。
在 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 步流程
- 登入幣安網頁,頭像 → 「API 管理」。
- 輸入 Key 標籤(Biabahub 命名規範:
用途-策略-伺服器-YYYYMM,例如spot-grid-us1-202607),點選「建立 API」。 - 選擇「HMAC-SHA256 系統生成」或「Ed25519 上傳公鑰」兩種模式,推薦 Ed25519(服務端不留私鑰)。
- 郵箱驗證碼 + 2FA 雙驗證後,頁面唯一一次展示 Secret / Passphrase,立即複製到密碼管理器。
- 編輯 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 白名單標準流程
- 在你的策略伺服器上執行
curl ifconfig.me或curl ipinfo.io/ip,獲取公網出網 IP。 - 若使用雲廠商,請從彈性 IP / 出網 NAT IP 面板確認(避免誤綁內網 IP)。
- 若走 CDN / Proxy,請確認最終出網 IP,不是入口 IP。
- 回到幣安 API 管理頁,編輯該 Key,貼上 IP,最多支援 4 個 IP。
- 儲存後立即用
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 條鐵律
- Secret 永遠不進程式碼庫:用環境變數、金鑰管理服務(AWS Secrets Manager / HashiCorp Vault)注入。
- recvWindow 保持 ≤ 5000ms:預設 5000,超過 60000 會被服務端拒絕,越大重放視窗越危險。
- NTP 時鐘同步:伺服器與幣安時鐘差超過 recvWindow 就會 -1021,反過來也是防重放。
- 請求日誌脫敏:任何 log 裡出現
signature=都要 mask 掉後 32 位。 - 異常回滾:簽名失敗連續 3 次立即報警,可能是 Secret 已被撤銷或伺服器被入侵。
- 超時上限:所有 requests 設定 timeout ≤ 5s,防止連線被劫持掛起。
五、90 天輪換與緊急撤銷
5.1 常規輪換節奏
- 提現 Key:90 天硬性到期,幣安強制。
- 交易 Key:Biabahub 內部規範 90 天輪換,與提現 Key 對齊。
- 只讀 Key:180 天輪換,降低運維負擔。
- 輪換流程:建立新 Key → 部署到策略 → 驗證 24 小時無異常 → 撤銷舊 Key,禁止並行超過 72 小時。
5.2 緊急撤銷 SOP
一旦懷疑 Key 洩露,按以下順序:
- 幣安 API 管理頁面點選「刪除 API」,立即失效。
- 同步撤銷該 Key 對應的策略程序,避免 -2015 錯誤重試打爆監控。
- 提現許可權 Key 洩露必須同時凍結賬戶,走「安全 → 緊急凍結」按鈕。
- 檢查最近 24 小時訂單、提現記錄,匯出 CSV 存檔。
- 透過官方工單提交事故報告,附洩露原因分析。
- 覆盤階段建議同步閱讀 幣安 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