Key Takeaways
An API key is a credential included in requests to formally authenticate access to an API.
API keys are necessary to perform any account or trade actions on the Binance APIs.
Binance supports multiple algorithms for signing API requests, such as HMAC, RSA, and Ed25519.
This article discusses how to store API keys in a secure way, API key permissions, and the different endpoints they apply to.
Introduction
An application programming interface (API) key is a unique identifier used by an API to recognize the application or user making the request. These keys help monitor and manage API usage, ensuring proper authentication and authorization of applications, much like the function of usernames and passwords.
When using Binance APIs, API keys are used as authentication and authorization for any operation related to the account or trade.
These keys must be kept strictly confidential and well-protected, as they provide full access to Binance accounts through the APIs.
In this article, we will discuss the advantages and disadvantages of different API algorithms and provide guidance on securely using API keys.
For more information on API Key terminology and best practices, please refer to the following article: What Is an API Key and How to Use It Securely?
Algorithms Comparison
Symmetric algorithm: HMAC
HMAC is widely supported by Binance APIs, and the secret key can be directly generated on the Binance website or app.
Pros:
Simplicity: Easy to implement and understand.
Performance: Fast computation, suitable for high-speed applications.
Compatibility: Widely supported across various platforms and libraries.
Integrity: Provides strong message integrity and authentication.
Flexibility: Can be used with different hash functions (e.g., SHA-256).
Cons:
Symmetric Key: Requires secure key distribution and management.
Scalability: Less suitable for large-scale systems requiring asymmetric encryption.
Key Size: Limited by the hash function's output size.
Security: Vulnerable if the key is compromised.
Non-repudiation: HMAC does not offer non-repudiation since both parties use the same key. It is important to rotate HMAC keys regularly and avoid storing them in plaintext or hardcoding them.
Asymmetric algorithms
Two of the most popular asymmetric algorithms are supported by Binance APIs:
RSA
Pros:
Asymmetric Encryption: Provides secure key exchange and digital signatures.
Non-repudiation: Ensures that a sender cannot deny sending a message.
Widely Used: Established and trusted in various security protocols (e.g., SSL/TLS).
Key Management: Easier to manage public and private keys compared to symmetric keys.
Security: Strong security based on the difficulty of factoring large numbers.
Cons:
Performance: Slower than symmetric algorithms, especially for large data.
Key Size: Requires larger key sizes for strong security, leading to increased computational overhead.
Complexity: More complex to implement and understand.
Resource Intensive: Requires significant computational resources for key generation and encryption/decryption.
Quantum Vulnerability: Potentially vulnerable to quantum computing attacks in the future.
Ed25519
Pros:
Performance: Fast signing and verification, suitable for high-speed applications.
Security: Strong security based on elliptic curve cryptography.
Key Size: Smaller key sizes compared to RSA, reducing storage and transmission overhead.
Deterministic: Produces consistent signatures, simplifying implementation.
Quantum Resistance: More resistant to quantum attacks compared to RSA.
Cons:
Complexity: Requires understanding of elliptic curve cryptography.
Adoption: Less widely adopted compared to RSA, though gaining popularity.
Compatibility: May not be supported by all legacy systems and protocols.
Binance strongly recommends using an Ed25519 private key with a passphrase, as it provides the most secure algorithm with optimal performance.
The passphrase adds an extra layer of security, ensuring that the private key file cannot be used without it.
Storing API Keys Securely
How to store the secrets
The Binance team has created multiple connectors in various programming languages to make it easier for developers to send API requests within their applications. These connectors are libraries that provide convenient interfaces to the Binance API, enabling seamless request sending and response parsing by simply supplying the required configuration parameters.
For more information about connectors, visit: Integrating Binance: APIs and Libraries.
Among these parameters, API keys are essential for authentication. We highly recommend configuring the client by specifying the path to the private key file instead of embedding the key content directly in your code. This practice should also be followed for the API Key and Secret Key. Additionally, it is strongly advised to avoid storing the API Key, Secret Key, or private key in plain text anywhere to ensure the security of your credentials.
The keys can be stored using the following mechanisms:
Store in configuration files:
We advise storing this information in files that the application can read, such as .ini or .properties files.
Ensure that these files are not tracked by git, either by keeping them outside of the project directory or by adding them to the .gitignore file.Store in environment variables:
Secrets can also be read by your application through environment variables.
It can be useful when the secrets are retrieved outside of the main application process, and can be used as such:
PASSWORD=$(./get_password.sh); my_application;Periodical rotation and remediation plan
As a preventive measure, we advise regularly generating new keys and removing the old ones.
API Keys are akin to passwords, and it is recommended to change them with similar regularity. Ideally, this should be done monthly or even more frequently.
If there is any suspicion that an API Key may have been compromised, such as being accidentally pushed to a git repository, we strongly recommend deleting the API Key and creating a new one.
IP Restrictions
It is strongly encouraged to restrict the usage of an API Key to a specific list of IPs.
Moreover, IP restriction is a must to enable withdrawal operations.
In order to know a public IP, you can use websites such as https://www.ipify.org/ or by command line:
curl https://api.ipify.orgCopy the public address IP and paste it into the “Restrict access to trusted IPs only (Recommended)”.
Sub-account
In case of a more complex setup, such as having dynamic IPs or giving an account access to limited resources, sub-accounts can be used.
The update of whitelisted addresses could be automated for sub-accounts using the following API: Add IP Restriction for Sub-Account API key.
Please find more information about sub-accounts here: Binance Sub-Account Functions and Frequently Asked Questions.
API Restriction options
Each API Key comes with a set of restrictions that define the actions it can or cannot perform.
We recommend enabling only the options that are essential for specific needs. Additionally, it is advisable to use multiple keys with different restrictions.
Enable reading
This option enables the API Key to execute requests for retrieving information about the account, specifically allowing only GET requests.
Users will be able to access account information, balance, transaction history, and similar data.
However, this option does not allow any modifications to the account, meaning placing orders or performing any other operations that would alter the state of the account is not permitted.
Enable Spot & Margin Trading
This option will allow any operation for Spot trading, meaning all the APIs that allow users to do any operation on the spot market, which would typically be buying crypto at the current market rate.
All the Spot API endpoints can be found here: Spot Trading.
Binance Margin Trading lets users borrow money against their assets and use leverage, making it easier to trade with more capital.
Please find more information about margin trading APIs here: Margin Trading.
Enable Margin Loan, Repay & Transfer
This permission allows users to loan, repay and transfer using APIS in the context of Margin Trading. This option will enable Borrow and Repay and Transfer.
Permits Universal Transfer
Universal Transfer API allows the user to transfer funds between different account types inside Binance. (e.g., from Spot account to USDⓈ-M Futures account).
Enable the following endpoint: User Universal Transfer.
Enable withdrawals
Binance offers users a way to withdraw assets using the APIs.
There are two options to do so:
1. Using the travel rule withdrawal:
The "Travel Rule" is a regulation that requires Virtual Asset Service Providers (VASPs) to exchange information about the parties involved in cryptocurrency transactions, mainly to prevent money laundering and terrorist financing.
Find more about the APIs here: Withdraw (for local entities that require travel rule) (only for travel-rule applied regions)
2. Using the capital withdrawal:
A capital wallet is a digital tool used to store and manage virtual assets like cryptocurrencies, stablecoins, and NFTs. These wallets can be either custodial, where a third party manages them, or non-custodial, where the user has full control.
Find more about the APIs here: Withdraw
Enable symbol whitelist
Specify the symbols the API Keys can operate with; this option can be used to limit the operations to specific symbols.
For example, an API key could be limited to the pair BTC/USDT, which means that only operations between BTC and USDT will be permitted.
For more complex setups, the symbol whitelist can be configured on sub-accounts.
Please find more information in the guide: How to Whitelist API Trading Symbol for Sub-Accounts?.
Enable FIX API Trading
FIX API is designed to be more efficient than REST and WebSocket APIs because it operates directly over the TCP protocol, eliminating request overhead.
It is intended for advanced users who require high throughput when accessing Binance APIs.
Unlike REST or WebSocket APIs, the FIX API is not user-friendly, as its requests and responses are not human-readable and must be managed programmatically.
This option will enable all the APIs listed in the following document: FIX API | Binance Open Platform
Enable FIX API Reading
This permission will allow only GET operations on the FIX APIs, so it ensures that no data will be changed.
Closing Thoughts
API Keys are utilized to authenticate and authorize a user when accessing Binance APIs. These keys are unique to each user.
Several algorithms are supported by Binance APIs: HMAC, RSA, and Ed25519 for compatibility purposes. However, we strongly recommend using Ed25519 with a passphrase. This algorithm provides high security, is supported by all Binance APIs, and offers the best performance.
Since API Keys grant access to a user's account, they should be stored and used with caution, as any leakage could pose a financial risk.
By adhering to the best practices described in this article, the risk of leakage can be minimized and render the keys unusable by unauthorized third parties if they are discovered.
Further Reading
Disclaimer: This content is presented to you on an “as is” basis for general information and educational purposes only, without representation or warranty of any kind. It should not be construed as financial, legal or other professional advice, nor is it intended to recommend the purchase of any specific product or service. You should seek your own advice from appropriate professional advisors. Where the article is contributed by a third party contributor, please note that those views expressed belong to the third party contributor, and do not necessarily reflect those of Binance Academy. Please read our full disclaimer here for further details. Digital asset prices can be volatile. The value of your investment may go down or up and you may not get back the amount invested. You are solely responsible for your investment decisions and Binance Academy is not liable for any losses you may incur. This material should not be construed as financial, legal or other professional advice. For more information, see our Terms of Use and Risk Warning.