Binance API Keyの3段階権限とIPホワイトリスト:プログラマティックトレードにおける最小露出面の設定
BiabahubチームがBinance API Keyの読み取り専用・取引・出金の3段階権限の違い、PassphraseとHMAC-SHA256署名の実例、IPホワイトリストにサーバーグローバルIPを紐づける手順、90日ローテーションの推奨サイクル、30秒でアカウントが空になった実事故のポストモーテムを徹底解説。設定所要時間は約15分です。
Biabahubで対応してきたAPI事故の中で最速のケースは、Key漏洩からアカウント残高がゼロになるまでわずか28秒でした。攻撃者は漏れたKeyでいきなり100倍レバレッジの逆張り注文を出し、強制ロスカットを誘発したのです。API KeyはBinanceのセキュリティ体系の中で「権限は最大、認証は最弱」に位置する存在です。本記事では3段階の権限、IPホワイトリスト、Passphrase、HMAC署名、ローテーションのリズムを一気に解説します。ブラウザ側で設定を確認したい方はBinance公式サイトから、モバイル側で確認したい方は
/ja/download/かBinance公式アプリをご利用ください。
結論:プログラマティックトレード用アカウントのAPI Keyはどう設定すべきか?
A:最低でも3つのKeyに分けてください。1つは監視用の読み取り専用、1つは戦略発注用の取引Key、1つは独立した出金用でしかも常時ほぼ無効化しておきます。 それぞれのKeyには業務上本当に必要な最小権限だけを付与し、すべてIPホワイトリストに紐付ける——あなたのサーバーのグローバルIPからしか呼び出せない状態にします。デフォルト権限のままIPホワイトリスト無しのKeyは、漏れれば30秒以内に丸ごと持っていかれます。一連の設定は所要時間約15分。関わる画面はAPI管理ページ、サーバーのアウトバウンドIP確認画面、あなたの戦略コード側の設定の3つです。IPホワイトリストを省く手抜きは、元本全損という代償を伴います。
一、3段階権限の境界と呼び出せるエンドポイント
BinanceのAPI権限は2024年の再設計以降、3段階に整理されました。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%は「現物取引」または「先物取引」のいずれか1段階で十分です。同一Keyに「出金」権限を絶対に上乗せしないでください。 出金権限は独立した1本のKeyにし、常時オフにしておくべきです。
1.2 出金権限に対する特別な制約
- 出金権限のKeyは必ずIPホワイトリストに紐付ける必要があります。Binanceは2024年以降このルールを強制しています。
- 出金権限のKeyは必ず送金先アドレスのリストを指定し、ホワイトリスト内アドレスにしか出金できません。
- 出金権限のKeyには90日の強制有効期限があり、期限が来ると強制的に更新(発行し直し)が必要で、延長はできません。
- 1回あたり出金限度額、1日あたり出金限度額を独立して設定でき、アカウントレベルの限度額と比較して小さい方が適用されます。
Biabahubチームの出金Keyは年間通して「無効化」状態にしてあり、月次の資金調達日に2時間だけ有効化し、使い終わったら即座に削除しています。
二、PassphraseとAPI Keyの生成フロー
Binanceは2025年下半期に上級APIユーザー向けとしてPassphrase機構を導入しました。OKXの初期の手法に近く、署名の外側にもう1つ鍵を掛ける仕組みです。
2.1 Key作成の5ステップ
- BinanceのWebにログインし、アバター → **「API管理」**へ。
- Keyのラベルを入力(Biabahubの命名規約:
用途-戦略-サーバー-YYYYMM。例:spot-grid-us1-202607)し、「APIを作成」をクリック。 - **「HMAC-SHA256 システム生成」または「Ed25519 公開鍵アップロード」**の2モードから選択。推奨はEd25519(サーバー側に秘密鍵が残らない)。
- メール認証コード+2FA認証を通すと、画面には一度だけSecret/Passphraseが表示されるので、即座にパスワードマネージャーへコピー。
- Keyを編集し、必要な権限にチェック、IPホワイトリストを紐付け、有効期間を設定します。
Q:Ed25519はHMAC-SHA256に比べて何が優れていますか? A:3点あります。 第一に、Binanceサーバー側には公開鍵しか保存されないため、仮にBinance内部データが漏洩しても秘密鍵は奪われません。第二に、(相対的に)耐量子性の高い署名アルゴリズムです。第三に、署名ごとにランダムな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を取得。 - クラウド事業者を使っている場合は、Elastic IP/アウトバウンドNAT IPのパネルから確認してください(プライベートIPを誤って登録しないため)。
- CDNやProxy経由の場合は、最終的なアウトバウンドIPを確認します(入口IPではありません)。
- BinanceのAPI管理ページに戻り、当該Keyを編集してIPを貼り付け。最大4つのIPまで登録可能です。
- 保存後、サーバーから
curl -H "X-MBX-APIKEY: ..."で/api/v3/accountを一度叩き、正常応答が返れば完了。
3.2 IPホワイトリストのよくある誤解
| 誤解 | 結果 | 正しいやり方 |
|---|---|---|
| プライベートIPを入力(192.168/10.x) | Binanceが拒否、Keyが即使えない | グローバルIPを入力 |
| CDNの入口IPを入力 | アウトバウンドIPが変わった時点で失効 | 最終アウトバウンドNAT IPを入力 |
| 家庭回線の動的IPを入力 | IPが変わるたびにKeyがゴミに | DDNS+手動更新で運用 |
| 0.0.0.0/0を入力 | ホワイトリスト無しと同義 | 絶対禁止 |
| 複数サーバーで同一IPを共用 | 1台が破られると全滅 | 1戦略1IP |
Biabahubチームは本番用Keyをすべて単一固定のElastic IPに紐付けており、IPの変更はチケットベースの承認フローを経て初めて実施できます。
3.3 IPホワイトリスト有無による攻撃コスト比較
| シーン | ホワイトリスト無し | ホワイトリスト有り | 攻撃コストの変化 |
|---|---|---|---|
| GitHubへSecretを誤コミット | 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で時計を同期:サーバーとBinanceの時計差がrecvWindowを超えると-1021エラー。逆にこれがリプレイ防止にもなります。
- リクエストログのマスキング:ログに
signature=が現れたら末尾32文字は必ずマスクします。 - 例外時のロールバック:署名失敗が3回連続したら即アラート。Secret失効かサーバー侵入の可能性があります。
- タイムアウトの上限:すべてのrequestsにtimeout ≤ 5sを設定。接続ハイジャックによるハングを防ぎます。
五、90日ローテーションと緊急撤回
5.1 通常時のローテーションリズム
- 出金Key:90日で強制失効。Binanceの強制ルール。
- 取引Key:Biabahub社内規約で90日ローテ、出金Keyと歩調を揃える。
- 読み取り専用Key:180日ローテで運用負担を軽減。
- ローテーションのフロー:新Key作成 → 戦略へデプロイ → 24時間異常なしを検証 → 旧Key撤回。並行稼働は72時間を超えないこと。
5.2 緊急撤回SOP
Key漏洩が疑われた瞬間、以下の順で実施します。
- BinanceのAPI管理ページで**「APIを削除」**をクリックし、即失効させる。
- 対応する戦略プロセスも並行して停止させ、-2015エラーのリトライがモニタリングを溢れさせないようにする。
- 出金権限Keyの漏洩時は同時にアカウントを凍結し、「セキュリティ → 緊急凍結」ボタンから操作。
- 直近24時間の注文・出金記録を確認し、CSVにエクスポートして保管。
- 公式チケットで事故報告を提出し、漏洩原因の分析も添付。
- ポストモーテムの段階ではBinance 2段階認証の移行とバックアップコード管理とBinance出金ホワイトリスト設定も併読し、防御体系を総点検してください。
六、実事故:30秒で残高ゼロになった技術リプレイ
2026年3月にBiabahubが対応した典型ケースをご紹介します。利用者A(以下「A」)がGitHubのパブリックリポジトリにデバッグコードをコミットしてしまい、その中にマスクされていないAPI_KEY/API_SECRETが含まれ、しかもIPホワイトリスト無しでした。
| タイムライン | 攻撃者の動作 | 利用者の損失 |
|---|---|---|
| T+0秒 | GitHub Pushがスキャンボットを起動 | 0 |
| T+8秒 | ボットがKey/Secretを取得し有効性を確認 | 0 |
| T+12秒 | 攻撃者がBTC永久先物で125倍逆張りポジションを立てる | 証拠金が凍結 |
| T+22秒 | 攻撃者が自分のVaultで同方向の注文を出して刈り取り | Aが強制ロスカット |
| T+30秒 | 攻撃者は8.4 BTCの利益、Aは12.6 BTCの損失 | 全損 |
事後分析:
- IPホワイトリストが有効なら、攻撃者はまずAのサーバーを陥落させる必要があり、攻撃コストは0から10万ドル級へ跳ね上がっていました。
- 出金権限を分離していれば、攻撃者は現金を直接持ち逃げできず、市場での見せ玉取引でしか搾取できなかったはずです。
- メール+Push通知を有効化していれば、Aは少なくともT+30秒時点でアラートを受信できました(既に手遅れですが)。
よくある質問
Q1:Binance APIにレート制限はありますか?
あります。REST APIはIP単位のレート制限で、重み上限はおよそ6000/min。発注系エンドポイントはUID単位で、おおよそ200回/10秒です。上限突破時は429または418が返り、418のステータスは5〜10分間IPをブラックリスト入りさせます。Biabahubの戦略にはbackoffを組み込み、429ヒット後は線形リトライで待機します。
Q2:Keyはサブアカウントで分離できますか?
できます。サブアカウントごとに独立してKeyを発行でき、メインアカウントのKeyとは権限を共有しません。企業ユーザーは事業ラインごとにサブアカウントとKeyを分け、「ある戦略のミスはそのサブアカウントの範囲でしか爆発しない」という影響半径の制限を作ることを推奨します。
Q3:Ed25519 Keyの秘密鍵はどう保管すれば良い?
一度生成したら使い切って消します。Biabahubの推奨フロー:ローカルのOpenSSLで鍵ペア生成 → 公開鍵をBinanceへアップロード → 秘密鍵をKMS(AWS KMS/GCP KMSなど)に即インポートし、ローカル側は物理的に破棄。戦略プロセスはKMSから秘密鍵を取り出してメモリにキャッシュし、再起動時に改めて取得します。
Q4:APIが延々と-1021のタイムスタンプエラーを返す場合は?
サーバーのNTPが未有効か、時計がずれているケースがほとんどです。Linuxならsudo timedatectl set-ntp true、Windowsならw32tm /resyncで強制同期してください。同期しても改善しないなら、Binanceのサーバー時刻GET /api/v3/timeとローカル時刻の差がrecvWindow未満か確認しましょう。
Q5:同じKeyで現物と先物を同時に運用できますか?
技術的には可能で、Binanceの権限設定でも現物/先物は別スイッチです。ただしBiabahubは分離を強く推奨します。現物の指値と先物の強制ロスカットではリスクの桁が全く違うため、Keyを共用するとどちらか一方の戦略のバグがもう一方に飛び火する可能性があります。
Q6:API Keyが期限切れになる前に通知は来ますか?
有効期限の7日前に公式メールで通知が届きます。Biabahubは自分の戦略側にも独自のカウントダウンアラートを仕込み、単一チャネル依存を避けることを推奨しています。
Q7:旧Keyを撤回した後、過去の注文は引き続き参照できますか?
参照できます。注文レコードはKeyと結合していません。撤回は署名チャネルを閉じるだけで、過去の注文はアカウントの取引履歴に残り、Web画面からCSVでエクスポート可能です。
リスクに関するご案内
本記事はBiabahubチームがまとめたもので、API KeyとIPホワイトリスト設定に関する技術教育を目的としています。投資助言、法的助言、特定戦略の損益に対する保証のいずれをも構成しません。プログラマティックトレードには、レバレッジ、強制ロスカット、スリッページ、ネットワーク遅延、取引所障害など多層のリスクが伴います。本記事のサンプルコードは教育目的のデモです。実運用の前には、完全なバックテスト、ペーパートレード、少額実運用の3段階を経て検証する必要があり、戦略結果はすべて利用者自身の負担となります。API Keyが漏洩した場合は直ちに撤回してください。「カスタマーサポートに送って原因調査を手伝ってもらう」といった要求はすべて詐欺です。Binance公式が、Secret/Passphrase/秘密鍵を要求することはありません。IPホワイトリストは万能ではなく、サーバーそのものが乗っ取られると攻撃者は正規IPからKeyを使えてしまいます。したがってサーバー本体も最小権限の適用、定期パッチ適用、ログ監査などの基礎的なセキュリティ運用が必須です。90日ローテーションは下限であって目標ではありません。高額残高アカウントは30日ローテやイベント駆動ローテを推奨します。公式登録はBinance公式サイト、公式アプリのダウンロードはBinance公式アプリからお進みください。
本ドキュメントは2026-07-01に公開、次回レビュー予定は2026-10-01です。