The Binance API IP whitelist is your most critical security measure. Once configured, only requests originating from designated IP addresses can use the API key to operate your account. Even if your key is leaked, unauthorized users cannot place orders. This article covers full configuration solutions for five scenarios: static IPs on cloud hosts, dynamic IPs for home broadband, dual-exit IPs, VPN proxies, and IPv6. It also includes scripts to check your current exit IP and addresses 10 common misconceptions. If you don't have a Binance account yet, please complete registration on the Binance Official Website; new users can Register for Free.
I. Core Rules for IP Whitelisting
| Rule | Description |
|---|---|
| Max IPs per Key | 30 |
| IP Type | IPv4 only (IPv6 is currently not supported) |
| CIDR Blocks | Not supported (each IP must be entered individually) |
| Effective Time | Immediate upon saving (usually within 30 seconds) |
| Withdrawal Permissions | Requires an IP Whitelist (withdrawal permissions are forcibly disabled without an IP whitelist) |
| Modification Frequency | No limit; can be adjusted at any time |
Important: Keys without an IP whitelist can never enable withdrawal permissions. This is a mandatory security rule enforced by Binance.
II. Scenario 1: Cloud Servers (Static IP)
This is the most ideal scenario. When creating your API key, directly enter the public IP of your cloud host.
1. Check Cloud Host Public IP
# Option 1: Query an external service
curl -4 ifconfig.me
curl -4 ipv4.icanhazip.com
curl -4 api.ipify.org
# Option 2: Alibaba Cloud metadata
curl http://100.100.100.200/latest/meta-data/eipv4
# Option 3: AWS metadata
curl http://169.254.169.254/latest/meta-data/public-ipv4
2. Configuration on Binance
Go to the Binance API Management page → Edit Key → Select "Restrict access to trusted IPs only (Recommended)" → Enter the IP addresses → Save.
Multiple IPs should be separated by commas:
1.2.3.4,5.6.7.8,9.10.11.12
3. Cloud Host Precautions
- Elastic IPs are not retained after unbinding; ensure they are removed from the Binance IP whitelist immediately.
- Auto Scaling Group instances have public IPs that change; they are not suitable for API whitelisting. Use a NAT Gateway to fix the exit IP instead.
- CDN/Reverse Proxies are not applicable—Binance sees the proxy provider's IP, not your backend server's IP.
III. Scenario 2: Home Broadband (Dynamic IP)
Home broadband IPs may change every 24 hours. Here are a few ways to handle this:
Option A: Unrestricted IP (Simplest but high risk)
Select Unrestricted (Less Secure) on the Binance API Management page. Disadvantages:
- Withdrawal permissions are automatically disabled.
- No protection if the key is leaked.
This is only suitable for data-reading scenarios (checking "Enable Reading" only).
Option B: Semi-Automated Whitelist Updates
Binance does not provide an API to update the whitelist; it must be modified manually via the web interface. Therefore, full automation is not possible.
However, you can use a semi-automated approach:
- Detect the current exit IP hourly.
- Compare it with the configured whitelist IP.
- If they don't match, send a notification via Telegram or another service.
- Manually log in to Binance to update.
Example script:
import requests
import time
CURRENT_WHITELIST = {"1.2.3.4"} # The IP set on Binance
TG_BOT = "TELEGRAM_BOT_TOKEN"
TG_CHAT = "YOUR_CHAT_ID"
def get_current_ip():
return requests.get("https://api.ipify.org").text.strip()
def notify(msg):
requests.get(
f"https://api.telegram.org/bot{TG_BOT}/sendMessage",
params={"chat_id": TG_CHAT, "text": msg}
)
last_ip = None
while True:
ip = get_current_ip()
if ip != last_ip:
if ip not in CURRENT_WHITELIST:
notify(f"IP changed to {ip}. Please log in to Binance to update the whitelist.")
last_ip = ip
time.sleep(3600)
Option C: DDNS + Fixed Entry (Recommended)
Use a cloud server with a fixed IP as a reverse proxy or jump host:
Home PC → SSH Tunnel → Cloud Server → Binance API
On the cloud server (e.g., a low-cost VPS):
# Establish an SSH tunnel on your home PC
ssh -N -L 8443:api.binance.com:443 [email protected]
Then, change the BASE_URL in your code to https://localhost:8443 (handle TLS certificate verification). Whitelisting the fixed IP of the cloud server is sufficient.
An even more elegant solution is setting up a WireGuard VPN, routing all traffic from your home PC through the VPS exit.
IV. Scenario 3: Multi-Server Load Balancing
Production-grade quantitative strategies are often deployed across multiple servers for disaster recovery:
Primary: Alibaba Cloud Tokyo Zone A (IP: 47.1.2.3)
Backup: AWS Tokyo Zone B (IP: 54.4.5.6)
Monitoring: Tencent Cloud Hong Kong (IP: 150.7.8.9)
Enter all three IPs on Binance, separated by commas:
47.1.2.3,54.4.5.6,150.7.8.9
Enhanced Security: Create independent keys for each server rather than sharing one. If one machine is compromised, you only need to revoke that specific key while others continue to run.
V. Scenario 4: VPN / Proxy Exit IP
1. Verify the Final Exit IP of the Proxy Chain
A VPN or proxy routes traffic through an exit point rather than your real IP:
# Query through a proxy
curl -x http://proxy.example.com:8080 ifconfig.me
# Or query after connecting to a VPN
curl ifconfig.me
Use the proxy exit IP for the whitelist.
2. Be Aware of Shared Exit Risks
Commercial proxy exit IPs may be shared by thousands of people. Such IPs:
- Frequently appear on Binance's blacklist (due to others using them for wash trading or money laundering).
- If one user triggers risk control, the entire exit IP may be blocked, affecting everyone sharing it.
- May not meet Binance's KYC compliance requirements, potentially triggering account reviews.
Commercial proxies are not recommended for API trading. A self-built VPS with a dedicated IP is the much safer choice.
VI. Scenario 5: Docker / Kubernetes Containers
The exit IP of a container is determined by the host network configuration:
1. Host Network Mode
# Docker Compose
services:
bot:
image: mybot
network_mode: "host" # Container uses the host IP
In this case, the container's exit IP = the host's public IP.
2. Bridge Network + NAT
services:
bot:
image: mybot
networks:
- default
Docker uses NAT by default, so the exit is still the host's public IP (unless the host has multiple network cards pointing to different exits).
3. Kubernetes
Unify exit IPs through a NAT Gateway or Egress Gateway. Cloud providers (GKE, EKS, Alibaba Cloud ACK) all support fixed Egress IP features.
VII. Common Reasons for IP Whitelist Failures
| Symptom | Cause | Solution |
|---|---|---|
| New IP not in whitelist; error -2015 | IP changed and was not synced | Log in to Binance and update. |
| IP unchanged after cloud host reboot, but calls fail | VPC route or firewall blocking | Check outbound rules. |
curl works, but Python calls fail |
Python using a socks5 proxy | Check http_proxy environment variables. |
curl ifconfig.me shows A, but Binance reports B |
Multiple network cards with different exit routes | Check with route -n. |
| Immediate failure after adding | Cache not yet refreshed | Wait 30 seconds and retry. |
| Exit IP changes to home IP after VPN disconnects | VPN lacks a kill switch | Configure iptables to block non-VPN traffic. |
VIII. Double Insurance: Application-Layer IP Verification
Even if Binance has restricted the IP, your program should self-check upon startup:
import requests
EXPECTED_IP = "1.2.3.4"
def verify_ip():
current = requests.get("https://api.ipify.org").text.strip()
if current != EXPECTED_IP:
raise SystemExit(f"Exit IP Anomaly: {current} ≠ {EXPECTED_IP}; Startup Aborted.")
print(f"IP Verification Passed: {current}")
verify_ip()
# Initialize Binance client after this
IX. Common Questions FAQ
Q1: How many IPs can be set for a single key?
A: Up to 30, entered into the same input field separated by commas. If you have more than 30 servers, we recommend creating multiple keys for different server groups.
Q2: Can mainland China IPs be added to the whitelist?
A: You can enter any IPv4 address; Binance servers do not reject specific regional IPs from the whitelist. However, direct connections to binance.com from mainland China can be unstable; using a Hong Kong or Singapore VPS as a relay is recommended.
Q3: What is the difference between an IP whitelist and a firewall?
A: An IP whitelist is Binance-side access control (restricting where requests come from), while a firewall is server-side access control (restricting what traffic enters). They are complementary and both should be configured.
Q4: My VPS supports IPv6, but Binance doesn't. What should I do?
A: Binance does not currently support IPv6 whitelists. Solution: Use curl -4 to force IPv4, or disable IPv6 at the system level:
# Linux
sysctl -w net.ipv6.conf.all.disable_ipv6=1
Q5: After setting a whitelist, must market data queries also come from that IP?
A: Yes, if you are using the API key in the request. The IP whitelist restricts all requests that include the X-MBX-APIKEY header, including signed endpoints and USER_DATA endpoints. Public market data (e.g., /ticker/price without headers) remains unrestricted.
After reviewing IP whitelisting strategies, return to the [Category Navigation](/en/vault/API Integration/) to explore other security hardening tutorials.