How to Use Binance Spot REST API?

Key Takeaways

The Binance Spot REST API enables users to interact with Binance's spot trading features programmatically.
There are multiple base URLs available for different user setups.
Proper definition of HTTP methods, query parameters, and endpoint security is essential for successful API requests.
The API returns response data in JSON format, organized chronologically.

Introduction

Binance offers different types of APIs for its diverse markets, including Spot, Futures, Margin, and Options trading, with each serving specific needs and use cases. Among these, there is the Spot REST API, which focuses on allowing developers to interact with Binance's Spot trading services programmatically.

Binance Spot REST API facilitates various functionalities, including fetching market data, executing trades, and managing account details. However, getting started with it can be challenging for newcomers due to its technical requirements and the need for precise configurations.

This article aims to clarify the process by providing an overview of the API's general request setup, what to expect from the response, and an example. Much of the information in the article is taken from the official Binance API documentation.

Prior knowledge of basic REST API architecture is required.

Binance Client Request

To interact with the Binance Spot REST API, users must select an appropriate base URL and understand how to structure their requests to the Binance server.

Base URLs

A base URL is the foundational part of the Uniform Resource Locator (URL) that serves as the main entry point for accessing resources on a web server or API.

Binance Spot API has different base URLs to accommodate varying user needs and network setups. Some different base URLs include:

https://api.binance.com: The general main base URL for all available functionalities of Spot REST API.
https://api1.binance.com: An alternative base URL that may give better performance but is less stable than the main one.
https://api-gcp.binance.com: An alternative base URL to the main one, utilizing the Google Cloud Platform (GCP) CDN.
https://data-api.binance.vision: For public market data only; ideal for requests focused solely on market data retrieval.

A complete list of base URLs can be consulted in the REST API documentation.

HTTP Methods and Parameters

The Spot REST API uses different HTTP methods, such as GET, POST, PUT, and DELETE, depending on the nature of the request:

GET requests require parameters to be included as a query string.
POST, PUT, and DELETE requests allow parameters to be sent either in the query string or in the request body with the application/x-www-form-urlencoded content type. Parameters can be mixed between the query string and request body, but if the same parameter is included in both, the query string parameter will take precedence.
Parameters may be sent in any order.

Endpoint security type and headers/parameters

Each endpoint has a security type that determines how you will interact with it. Those types include:

NONE: The endpoint can be accessed freely.
TRADE: The endpoint requires sending a valid API key and signature.
USER_DATA: The endpoint requires sending a valid API key and signature.
USER_STREAM: The endpoint requires sending a valid API key.

API keys must be included in the request header using the X-MBX-APIKEY header to authenticate the user's identity when accessing secured endpoints.

TRADE and USER_DATA endpoints are SIGNED endpoints, which require additional mandatory parameters: timestamp and signature.

timestamp: Represents the millisecond timestamp when the request was initiated.
signature: Ensures the integrity and authenticity of the request by verifying that it was generated by a legitimate user. It can be included in the query string or request body. The Binance GitHub repository binance-signature-examples contains examples to help users learn how to build signatures.
recvWindow (optional): Specifies the time window (in milliseconds) during which the request remains valid.

Binance Server Response

Format and data

All responses from the Binance Spot REST API are delivered in JSON format.

The data is ordered from oldest to newest (ascending order), allowing users to process the data chronologically and ensure consistency when handling time-sensitive information.

Time and timestamp values are provided in milliseconds to maintain uniformity across the API.

Error codes

The Binance API returns error codes for various issues, such as invalid requests, authentication failures, or rate limit breaches. Spot error responses include a code and message, e.g.:

{

  "code":-1121,

  "msg":"Invalid symbol."

}

These error codes help users diagnose and resolve issues quickly, and it is important to handle them gracefully in applications to maintain stability.

Users can refer to Binance Error Codes for a complete list of error codes.

Rate limits

To ensure fair usage and maintain server performance, Binance enforces rate limits on API requests. These limits specify the maximum number of requests that can be made within a specific time frame. If a user exceeds these limits, they may receive an error response indicating that the rate limit has been exceeded.

Managing rate limits properly is crucial to avoid disruptions in service and ensure smooth operation of applications that interact with the Binance API.

Binance Request Example: Account’s Current Information

cURL command

curl -H "X-MBX-APIKEY: CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ" -X GET "https://api.binance.com/api/v3/account?timestamp=1729241635546&signature=be3e476353b73d48197cf309798ae0b18ef16f9bef48b65bc16af677336326e8"

Security Type: /api/v3/account is classified as USER_DATA.
- This endpoint requires the inclusion of the request header X-MBX-APIKEY, containing a valid API key.
- As a SIGNED endpoint, it mandates the presence of two parameters: timestamp and signature.
HTTP Method: GET
Base URL: https://api.binance.com
Request Parameters: These are appended as a query string to the URL.

The provided example cannot be used to yield a valid 200 status code response due to the use of an invalid API Key and signature, along with a timestamp referencing a past value. However, a successful response example can be found in the Binance Spot API documentation in the Account Information section.

Binance Connectors Examples

In contrast to the cURL command, connectors abstract the underlying API calls with the intention of providing a more user-friendly interface. However, the submitted request data to the server is the same.

Closing Thoughts

The Binance Spot REST API is one of the types of API used by developers looking to automate their activities on the Binance Spot market. Understanding how to properly construct REST API requests and interpreting the JSON responses is crucial for efficient usage and secure interactions with the platform. While the initial setup can seem complex, following a structured approach can simplify the process and enable users to leverage Binance's full range of spot trading capabilities.