幣安 API key 許可權管理完整教程|IP 白名單+HMAC 簽名+金鑰輪換
本文覆蓋幣安 API key 只讀/交易/提現三檔許可權、IP 白名單繫結、HMAC-SHA256 簽名、限流閾值、key 洩露應急流程與季度輪換策略,讓量化與套利賬戶零信任裸奔風險。
一句話直答:幣安 API key 採用「只讀 / 現貨合約交易 / 提現」三檔許可權模型,建議每一個 key 都開啟 IP 白名單、金鑰每季度輪換、提現許可權僅在必要機器人上啟用。任何要求把 API secret 發給「策略作者」「共享收益」的所謂合作都是騙局,幣安主賬戶不會透過任何官方渠道索取使用者的 API secret。
API key 是量化、套利、跨交易所對沖的通道,但也是資金歸零的高風險入口。本文按許可權模型、IP 白名單、HMAC 簽名、限流機制、洩露應急、輪換策略六大部分拆解。核對入口時可以先看 幣安官網入口,App 版從 下載頁 拿。配置完 key 後可以到 幣安官網 做一次 IP 白名單驗證,或者用 幣安官方App 檢視 API 使用記錄。
API key 三檔許可權模型
幣安 API key 的許可權勾選是分檔獨立的,建議按最小許可權原則勾選。不同許可權的組合直接決定 key 洩露後的最大損失。
| 許可權檔 | 關鍵動作 | 洩露最大損失 | 建議使用場景 |
|---|---|---|---|
| 只讀 | 查詢賬戶餘額 / K 線 / 訂單歷史 | 洩露資訊 | 資料分析、視覺化 |
| 現貨交易 | 下單 / 撤單 / 查詢持倉 | 惡意對倒 | 量化策略、套利 |
| 合約交易 | 合約下單 / 調整槓桿 | 高槓杆爆倉 | 合約量化 |
| 提現 | 白名單地址提現 | 白名單內額度 | 極少使用 |
| 全域性白名單例外 | 允許非白名單地址 | 完全資產 | 強烈不推薦 |
A:任何量化策略預設不需要提現許可權,只有資金歸集機器人才需要,且必須與主賬戶白名單強繫結;一旦解除 IP 白名單,key 應立即禁用。
key 與 secret 的對稱保護
API key 是公開欄位,洩露不致命;API secret 是簽名金鑰,洩露即等於賬戶失控。secret 只在建立時展示一次,之後無法從後臺看到;建立時必須立即用密碼管理器或環境變數儲存,不要寫在原始碼裡、Git 倉庫裡、聊天記錄裡。
IP 白名單繫結 4 步
IP 白名單是 API 層最有效的兜底措施,標準配置流程:
- 確定伺服器出口 IP:在生產伺服器上執行
curl https://ifconfig.me或dig +short myip.opendns.com @resolver1.opendns.com得到公網出口 IP;如果是 IPv6 環境,同時記錄 IPv6 字首。 - 繫結 IP 到 API key:在幣安 API 管理頁面 → 編輯 key → 勾選「限制訪問 IP」→ 貼上 IP(多個用逗號分隔,最多 30 個)→ 2FA 驗證儲存。
- 測試請求:在生產伺服器發起一次簡單請求(如 GET /api/v3/account)驗證簽名 + IP 均透過;從其他 IP 發起同一請求應返回 -2015 錯誤。
- 靜態 IP 保障:如果伺服器 IP 是動態的(家用寬頻、部分 VPS),需要繫結彈性 IP 或用 NAT 閘道器;否則 IP 變動後 API 立即失效。
⚠️ 風險提示:任何要求你「先關掉 IP 白名單再執行策略」的第三方策略框架都要警惕。開源策略框架無需關閉白名單,商業策略平臺也會有對應白名單說明。
常見雲廠商出口 IP 特性
AWS 預設彈性 IP 是靜態的,繫結後不換即可;阿里雲、騰訊雲類似。Cloudflare Workers 或 Vercel Edge 屬於動態出口,不適合直接對接幣安 API;建議中間放一個靜態 IP 的代理層。
HMAC-SHA256 簽名機制
幣安現貨、合約、期權 API 全線使用 HMAC-SHA256 簽名。每個請求的簽名 = HMAC-SHA256(query_string, secret),簽名欄位名 signature。
- 請求必須帶 timestamp 引數(毫秒時間戳)。
- recvWindow 預設 5000 毫秒,最大 60000 毫秒。
- 時間戳與伺服器時間偏差超過 recvWindow 時報 -1021 錯誤。
- 簽名放在 query string 末尾或 body 中,作為最後一個欄位。
A:recvWindow 建議保持在 5000 毫秒,過大會給攻擊者更大的重放視窗;家用寬頻下如果頻繁 -1021,先同步 NTP 而不是調大 recvWindow。
簽名示範
以 Python 為例:signature = hmac.new(secret.encode(), query_string.encode(), hashlib.sha256).hexdigest()。secret 編碼錯誤、query_string 中欄位順序被改都會導致簽名失敗;建議用官方 SDK 或成熟第三方庫,別自己拼字串。
WebSocket 私有頻道認證
現貨 user data stream 需要先用 REST 拿 listenKey,然後接 WebSocket;listenKey 有 60 分鐘有效期,需要每 30 分鐘 keepalive 一次。忘記 keepalive 會導致私有頻道靜默斷開,是新手最常見的坑之一。
限流機制
限流是保護交易系統的關鍵,也是量化開發者必須掌握的欄位:
| 端點類別 | 權重上限 | 計時視窗 | 備註 |
|---|---|---|---|
| 現貨公共 | 6000 權重 | 1 分鐘 | IP 維度 |
| 現貨交易 | 1200 權重 | 1 分鐘 | key 維度 |
| 合約公共 | 2400 權重 | 1 分鐘 | IP 維度 |
| 合約交易 | 100 單/10 秒 | 滾動 | key 維度 |
| WebSocket 連線 | 5 連線/IP | 長連 | 別頻繁重連 |
A:響應頭 X-MBX-USED-WEIGHT-1M 會告訴你當前分鐘已用權重,編寫策略時必須監控這個欄位並做退避;一旦觸發 429,短時間會封禁 IP。
觸發 418 的後果
連續觸發 429 未退避會升級為 418(IP 封禁),封禁從 2 分鐘起,最長 3 天。418 期間即便切換 API key 也無法訪問,因為封禁是 IP 維度的;因此策略必須嚴格做本地限流。
key 洩露應急 5 步
發現 key 可能洩露時,5 分鐘內完成以下動作:
- 立即禁用 key:登入幣安網頁版 → API 管理 → 找到可疑 key → 立即禁用(不是刪除);禁用後所有請求立即失敗。
- 修改主賬戶密碼:即便 API 洩露與密碼無關,也建議同步改密,避免連鎖風險。
- 強制下線所有會話:賬戶 → 安全 → 裝置管理 → 全部登出;同時 2FA 重置一次。
- 檢查白名單變動:如果攻擊者利用 key 修改了白名單,24 小時冷卻期內還有救;立刻走人工客服工單凍結賬戶。
- 審計最近 30 天流水:下載交易歷史 + 提現歷史 → 逐筆核對;異常交易應即時截圖存證。
A:禁用而不是刪除的原因是保留證據,刪除後無法透過 API 查詢該 key 的歷史請求,事後追溯困難。
事後覆盤
事後建議做一次完整覆盤:哪臺機器出的 secret、日誌裡有沒有明文 secret、IP 白名單是否曾解除過。80% 的洩露源於把 secret 提交到 Git 倉庫或者放在明文配置檔案裡。
金鑰輪換策略
推薦按 3 檔節奏做金鑰輪換:
- 只讀 key:每半年輪換一次,主要防止長期洩露被無痕利用。
- 交易 key:每季度輪換一次,配合策略版本釋出節奏。
- 提現 key:每次任務結束立即禁用,下次任務前重新申請;不做常駐。
- 測試 key:每次測試完立即禁用;測試 key 從不帶交易許可權。
輪換後建議登入 幣安官網 檢查歷史 key 是否已全禁用;或者在 幣安官方App 裡檢視 API 使用記錄,發現異常 UA 立即處理。
常見問題
Q1:只讀 API key 洩露也需要處理嗎?
A:需要。只讀 key 會暴露持倉、訂單、餘額,可能被用於策略反向對倒或釣魚定位;發現洩露仍應立即禁用。
Q2:一個賬戶能開多少個 API key?
A:幣安現貨最多 30 個,合約獨立算最多 30 個。建議一個策略一個 key,方便隔離和審計。
Q3:為什麼 -1021 時間戳錯誤頻繁出現?
A:一般是本地時鐘沒同步。Linux 用 chronyd / systemd-timesyncd,Windows 開啟自動同步時間;家用寬頻偏差往往在幾百毫秒到秒級。
Q4:能不能把 API secret 儲存在環境變數裡?
A:可以,且是推薦做法。但要防止環境變數被 dump 到日誌,特別是 CI/CD 環境;用 secrets manager(AWS Secrets Manager、HashiCorp Vault)更穩妥。
Q5:API key 顯示未啟用是被凍結了嗎?
A:可能是賬戶風控觸發,可能是 KYC 狀態變化。先看郵箱有無風控通知,工單能加急處理。
Q6:合約 API 與現貨 API 是同一個 key 嗎?
A:是的,一把 key 覆蓋現貨 + 合約 + 期權,許可權勾選各自獨立。建議合約與現貨用不同 key,隔離風險。
Q7:API 手續費能有折扣嗎?
A:VIP 等級達標後,API 交易本身就享受與網頁一致的手續費折扣;不需要額外申請。BNB 抵扣仍適用於 API 交易。
Q8:洩露的 secret 能撤銷嗎?
A:不能撤銷 secret 本身,但可以禁用 key 使其失效。secret 是不可再生的一次性欄位,洩露就必須換 key。
風險提示
⚠️ 幣安官方從不透過郵件、Telegram、Discord 索取使用者的 API secret。任何號稱能「拉高收益率」「共享策略」但要 secret 的都是騙局;開源量化框架可以本地部署,從不需要把 secret 傳送給第三方伺服器。
文件釋出於 2026-07-08,下次複測計劃 2026-10-08。