How to Configure Binance API Key Permissions and IP Whitelist in 2026
Biabahub breaks down the three tiers of Binance API permissions — read-only, trade, withdraw — with Passphrase and HMAC-SHA256 signing samples, IP whitelist steps, a 90-day rotation cadence, and a 30-second account-drain case study. Setup takes about 15 minutes.
The fastest API breach Biabahub has ever triaged took 28 seconds from key leakage to a zeroed account — the attacker used the leaked key to open a 100x reverse futures order that instantly liquidated the victim. API keys are the "highest permission, weakest verification" slice of Binance's security surface. This guide walks through the three permission tiers, IP whitelisting, Passphrase support, HMAC signing, and rotation cadence. To review any of this in the browser use Go to Binance Official Site. To confirm on mobile, visit
/en/download/or use Download Binance App.
Straight Answer: How Should an Algo Account Split API Keys?
A: Break every algo account into at least three keys — one read-only for monitoring, one trade key for the strategy, and one withdrawal key that stays dormant. Grant each key only the minimum permission the workload actually needs, and bind them all to an IP whitelist so only your server's public IP can call them. A key with default permissions and no whitelist can be drained in 30 seconds. The whole configuration takes about 15 minutes across three surfaces: the API management page, the server's egress IP, and your strategy config. Skipping the IP whitelist costs you the entire principal.
1. Boundaries of the Three Permission Tiers
Binance restructured API permissions in 2024 into three tiers. Biabahub maps them as follows.
1.1 Permission, Endpoints, and Risk Grid
| Permission | Example Endpoints | Cannot Call | Risk | Consequence of Leak |
|---|---|---|---|---|
| Read-only | GET /account, GET /myTrades, GET /openOrders | Any POST/DELETE | Low | Privacy loss, position hunting |
| Spot trade | POST /order, DELETE /order | Futures, margin borrow, withdraw | Medium | Reverse orders + wash trading |
| Futures trade | POST /fapi/v1/order, POST /fapi/v1/leverage | Withdraw, external transfer | High | 100x reverse liquidation |
| Withdraw | POST /wapi/v3/withdraw | — | Extreme | Everything gone in 30 seconds |
Biabahub's takeaway: 99% of production strategies only need one of "spot trade" or "futures trade" — never stack "withdraw" on top. Withdraw must live on its own key with default-off.
1.2 Special Constraints on the Withdraw Permission
- Withdraw keys must be bound to an IP whitelist. Binance enforced this rule in 2024.
- Withdraw keys must be pinned to a target address whitelist; funds can only leave to those addresses.
- Withdraw keys carry a hard 90-day expiry and cannot be renewed — you must rotate.
- Per-transaction and daily caps sit at the key level and are ANDed with the account cap.
At Biabahub the withdraw key stays disabled 361 days a year and is only reactivated for the two-hour monthly treasury sweep before being deleted again.
2. Creating a Key With Passphrase
For advanced API users Binance rolled out a Passphrase mechanism in H2 2025, mirroring OKX's earlier design. It's a second lock on top of signing.
2.1 Five Steps to Mint a Key
- Log in on Binance web, avatar → API Management.
- Enter the key label (Biabahub convention:
purpose-strategy-server-YYYYMM, e.g.spot-grid-us1-202607), click Create API. - Pick HMAC-SHA256 system-generated or Ed25519 upload public key — we recommend Ed25519 (the server never sees your private key).
- After email code + 2FA, the page displays your Secret / Passphrase exactly once. Paste it straight into your password manager.
- Edit the key: tick the permissions you need, bind the IP whitelist, set an expiry.
Q: Why is Ed25519 better than HMAC-SHA256? A: Three reasons. First, Binance's servers only store your public key, so even a Binance-side data leak cannot recover your private key. Second, the signing algorithm is more quantum-resistant (relatively speaking). Third, each signature carries a random nonce, making replay attacks harder. The downside is that some older client libraries do not support it; use the latest python-binance / ccxt.
2.2 Key Naming Conventions
| Field | Example | Purpose |
|---|---|---|
| Purpose | spot / futures / readonly / withdraw | Permission tier is obvious |
| Strategy | grid / martin / dca / monitor | Rotations easy to trace |
| Server | us1 / hk2 / local | Aligns with whitelist |
| Year-month | 202607 | Expiry = creation + 90 days |
Anti-patterns like test, api1, or MyKey correlate with 40% of the incidents in our post-mortem archive — after ops rotation nobody knows who owns the key or whether it can be deleted.
3. IP Whitelist: The Step Most Often Skipped and the One That Matters Most
An unwhitelisted key is a house key taped to a lamp post. Anyone with Key + Secret opens the door.
3.1 Standard Whitelist Flow
- On your strategy server run
curl ifconfig.meorcurl ipinfo.io/ipto get the public egress IP. - On cloud providers confirm through the Elastic IP / NAT egress IP console (never bind the private IP by mistake).
- If you sit behind CDN or proxy, make sure you are recording the egress IP, not the ingress IP.
- Return to Binance's API management page, edit the key, paste in the IP — up to four IPs per key.
- Save, then immediately test with
curl -H "X-MBX-APIKEY: ..."against/api/v3/accountfrom that server. A clean 200 confirms success.
3.2 Common Whitelist Mistakes
| Mistake | Consequence | Correct Approach |
|---|---|---|
| Private IP (192.168 / 10.x) | Binance rejects, key becomes unusable | Use public IP |
| CDN ingress IP | Fails once egress IP shifts | Use the actual NAT egress IP |
| Home broadband dynamic IP | New IP kills the key | Use DDNS + manual updates |
| 0.0.0.0/0 | Equivalent to no whitelist | Absolutely forbidden |
| Same IP for many servers | One breach cascades | One strategy per IP |
Every production key at Biabahub is bound to a single fixed Elastic IP and every IP change goes through a ticket.
3.3 Attack Cost Before and After Whitelisting
| Scenario | No Whitelist | With Whitelist | Attack Cost Delta |
|---|---|---|---|
| Secret pushed to GitHub | Scanner bot uses it in 30 seconds | Blocked | From free to compromising your server |
| Server logs harvested | Immediately usable | Blocked | Attacker also needs control of the whitelist IP |
| Employee leaves with the key | Immediately usable | Blocked | Attacker needs to breach corporate network |
Conclusion: whitelisting shifts the attack bar from "social engineering / credential stuffing" to "server intrusion". The defensive gain is orders of magnitude.
4. Minimal HMAC-SHA256 Signing Example
Below is a copy-pastable implementation you can diff against your own.
4.1 Python Reference
import time
import hmac
import hashlib
import urllib.parse
import requests
API_KEY = "read from password manager, never hard-coded"
API_SECRET = b"read from password manager, never hard-coded"
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 Six Iron Rules for Signing
- Secrets never enter the codebase: inject via environment variables or a KMS such as AWS Secrets Manager or HashiCorp Vault.
- Keep recvWindow at 5000 ms or less: the default is 5000, values over 60000 are rejected, and larger windows widen the replay attack surface.
- Keep NTP in sync: any drift larger than recvWindow yields -1021, which also blocks replays going the other way.
- Mask signatures in logs: any log line containing
signature=should mask the last 32 characters. - Alarm on failure: three consecutive signing failures should page — the secret may have been revoked or the server compromised.
- Timeout ceiling: every
requestscall must settimeout ≤ 5sso a hijacked connection cannot hang forever.
5. 90-Day Rotation and Emergency Revocation
5.1 Normal Rotation Cadence
- Withdraw keys: hard 90-day expiry enforced by Binance.
- Trade keys: Biabahub rotates every 90 days to align with the withdraw key.
- Read-only keys: 180-day rotation reduces ops noise.
- Rotation flow: mint the new key → deploy to the strategy → observe 24 hours → revoke the old key. Never keep both keys live for more than 72 hours.
5.2 Emergency Revocation SOP
Once you suspect a leak, act in this order:
- Click Delete API in the Binance API management panel — the key is instantly disabled.
- Kill the corresponding strategy process to stop -2015 error retries from flooding monitoring.
- If a withdraw key leaked, simultaneously trigger Security → Emergency Freeze.
- Export order and withdrawal history for the last 24 hours as CSV.
- File an incident report via the official ticket system with a root-cause analysis.
- During the post-mortem, read Binance 2FA Migration and Backup Code Management and Binance Withdrawal Whitelist Setup to shore up the rest of the perimeter.
6. Live Case: 30 Seconds to Zero
In March 2026 Biabahub handled a textbook incident. User A committed debug code to a public GitHub repo containing unmasked API_KEY and API_SECRET, with no IP whitelist.
| Timeline | Attacker Action | User Loss |
|---|---|---|
| T+0s | GitHub push triggers scanner bot | 0 |
| T+8s | Scanner extracts Key/Secret and verifies validity | 0 |
| T+12s | Attacker opens 125x reverse perpetual on BTC | Margin frozen |
| T+22s | Attacker uses their own vault to farm the other side | A is liquidated |
| T+30s | Attacker profits 8.4 BTC, A loses 12.6 BTC | Total loss |
Retrospective:
- With IP whitelisting, the attacker would have had to compromise A's server first, moving attack cost from zero to six figures USD.
- With split withdraw permissions, the attacker could not have wired funds out and would have been limited to market-based extraction.
- With push + email alerts, A could have received a warning by T+30s (too late, but faster than nothing).
FAQ
Q1: Does Binance API rate-limit?
Yes. REST endpoints are throttled per IP at roughly 6000 weight/min; order endpoints are throttled per UID at about 200 requests every 10 seconds. Breach the limit and you get 429 or 418; a 418 blacklists the IP for five to ten minutes. Biabahub strategies build in linear back-off after any 429.
Q2: Can keys be scoped per sub-account?
Yes. Every sub-account can mint its own keys that share no permissions with the master. Enterprise users should split sub-accounts by product line and mint per-sub-account keys so a strategy bug's blast radius stays contained.
Q3: How do you store the Ed25519 private key?
Generate it, use it, and delete it. Biabahub's recommended flow: generate the pair locally with OpenSSL → upload the public key to Binance → import the private key into KMS (AWS KMS / GCP KMS) → physically wipe the local file. The strategy pulls from KMS and caches in memory; a restart re-pulls.
Q4: What if the API keeps returning -1021 timestamp errors?
Almost always NTP is off or drifted. Run sudo timedatectl set-ntp true (Linux) or w32tm /resync (Windows) to force sync. If it still fails, compare GET /api/v3/time against local time and confirm the delta is smaller than recvWindow.
Q5: Can one key handle both spot and futures?
Technically yes — Binance treats spot and futures permissions as separate switches. Biabahub strongly recommends splitting: spot placement errors and futures liquidation are wildly different risk classes; sharing a key means either strategy's bug can wreck the other.
Q6: Will Binance notify me before a key expires?
Binance emails seven days before expiry. Biabahub also adds an expiry countdown alert inside the strategy itself so you never depend on a single channel.
Q7: After revoking a key, can I still query historical orders?
Yes. Order records are decoupled from keys. Revoking a key just closes the signing channel; the ledger stays in your account and you can export CSV from the web.
Risk Notice
This piece, produced by the Biabahub team, is educational content on API key and IP whitelist configuration. It is not investment advice, legal advice, or a promise about any specific strategy's PnL. Algo trading involves leverage, liquidation, slippage, network latency, and exchange outages; the sample code is illustrative only. Before running it live, walk through full backtesting, paper trading, and small-scale live validation. If a key leaks, revoke it immediately. Any message claiming that "support needs it for investigation" is a scam — Binance never asks for Secret, Passphrase, or private keys. IP whitelisting is not a silver bullet: once your server is breached, an attacker can hit the key from the whitelisted IP. Keep the host itself under least-privilege, patched, and audited. 90-day rotation is a floor, not a target; high-value accounts should rotate every 30 days or on event triggers. To register on Binance use Go to Binance Official Site. To download the official app use Download Binance App.
Published 2026-07-01, next review 2026-10-01