The purpose of this series is to introduce you to Binance’s REST API and to teach you how to interact with it. By the end, you should be confident in your ability to query information about the markets and your position and to place a range of different order types.
We’re going to use the testnet for our purposes. This will give us some funds with no real-world value to play around with. They function in exactly the same way as real coins and tokens, so once you’re comfortable with the API, you can start to use it to trade real funds.
- Start by heading over to the Spot Test Network.
- To get access, you’ll need to log in with a GitHub account. Create one if you haven’t already.
- Click Authenticate and sign in via GitHub.
- Under API Keys, you’ll be informed that you don’t have keys registered. Click on Generate HMAC_SHA256 Key to create a pair.
- On the next screen, give the keys a label. Call them whatever you want and hit Generate.
- You’re presented with two keys: the API Key and the Secret Key. It’s important that you record these now. You’ll need to start the key creation process again if you don’t. We recommend storing them on your machine’s notes app for easy copy-pasting later.
Downloading and installing Postman
Postman is an API Collaboration platform. It’s a perfect starting point for us – we’ll have access to collections of Binance requests that we’ll test without needing to write a single line of code.
Once that’s completed, locate it in your file explorer and install it. Fire up the application, and we’re good to go! Note that you can create an account to log in, but it isn’t necessary. If you want to skip that step, just select the option to do so at the bottom of the window.
Creating the environment
At this stage, you should have an interface that resembles the following.
The download shouldn’t take very long. Find it in your file explorer and unzip it. Then, we can head back into Postman.
- Select Import, and navigate to the folder you’ve just extracted (binance-postman-api).
- Enter it, then enter the environments folder.
- You’ll now see two files (one for mainnet and one for testnet). The one we’re after is binance_com_spot_testnet_api.postman_environment.json. Make sure you’ve got the correct one because our keys won’t work with the other.
On this screen, leave the timestamp and signature fields blank. These two values will be automatically created upon each request.
Importing the collection
Now we’re going to import the collection – this is an extensive assortment of requests that do the heavy lifting for us when we’re making calls. To load it into our environment:
- Click Import in the top left corner.
- In the popup, under the File tab, select Upload Files.
- We’re looking for the binance-postman-api folder again. Locate and open it.
- This time, enter collections in the subdirectory.
- There are two files here again. One is for working with the futures API. But we’re working with the spot one, so you’ll need to select the binance_spot_api_v1.postman_collection.json file.
- You should now see a confirmation screen that identifies the import as being in the Postman Collection format. Select Import.
Under the Collections tab to the left of the window, you’ll now notice that we have a folder with over 100 requests. Congratulations! We’re good to go. In the next section, we’ll take a look at the kinds of requests we can make.
If you expand the folders under the Collections tab, you’ll see that we have a bunch of different requests we can make. From the color-coding, you might note that there are three types of methods we can use:
- GET: The GET method is used to retrieve stuff from a server. We’ll use this to find out information about your account balance, asset prices, etc.
- POST: We’ll generally use the POST method to create information on a server. This is needed for things like placing orders, requesting withdrawals, etc.
- DELETE: The DELETE method is a request for the server to delete information. It’ll come in handy for canceling orders.
Find the list of symbols and the trading rules
Time for our first request! We’re going to get the symbols we can trade on the exchange and the trading rules:
This one doesn’t take any additional parameters – you could copy and paste that into your address bar, and you’d get a response. But for requests where we include several parameters, Postman makes it easy to see and modify them.
In the uppermost highlighted section, you’ll see some important information:
- the status of the response (200 means we’ve been successful, 400-499 means we’ve run into an issue)
the time taken to receive the response (less than a second)
the size of the response (~22KB).
In the second box is the bulk of the response. It’s been pretty-printed it so that it’s a bit easier on the eyes. This contains information on the exchange itself, as well as the pairs you can trade and their minimum/maximum amounts.
It looks like a lot of information, but the format makes it very easy to work with programmatically. When writing scripts to interact with it, you’ll easily be able to pick out specific properties of specific elements from the response.
Check the account balances
Let’s check what assets we have, and how much of each:
Congratulations on your newfound (non-existent) wealth!
How to get the current price for a symbol
We can go about getting the current price of an asset in different ways. Perhaps the simplest is with the following request:
As with the previous, you can change the symbol variable or remove it completely and get the latest price for all symbols.
Check the current order book depth
Order book depth (also referred to as depth of market, or DOM) can tell us a lot about the market. We’re going to make a call that will return some useful information:
When we send this with the default values (Market > Order Book), we’re sent back a response that tells us about the bids and asks for BTCUSDT. The testnet server won’t yield as much data as the actual one, so below is a screenshot of what you would expect to see in a real environment:
In the highlighted section above, we can see the first bid. Since we’re looking at the book for BTCUSDT, the upper number is the price that someone is willing to pay for your BTC. Below is the amount they’re willing to buy. What this says, therefore, is that this order is asking for 0.999 BTC at a rate of 9704.65 USDT per BTC. If we continued to scroll down, we would see the offer price decrease – representing buyers that would pay less.
The top offer will naturally be the most attractive one if you’re looking for bang for your buck. That said, if you’re trying to market sell, say, 3 BTC, you’ll only be able to sell 0.999 BTC for the best price. You’ll need to take the subsequent (cheaper) offers until the entirety of your order is filled.
Place a test order
Now we’re going to post a test order.
You can see we have many more parameters involved. Let’s walk through the checked ones:
- symbol – we’ve come across this one previously. This is the pair you want to trade.
- side – here, you’ll stipulate whether you want to BUY or SELL. With the BTCUSDT pair, BUY indicates that you want to buy BTC for USDT, whereas sell will sell BTC for USDT.
- type – the type of order you want to submit. Possible values (detailed here):
- timeInForce– this parameter expresses how you want the order to execute:
- GTC (good till canceled) – perhaps the most popular setup, GTC will ensure that your order is valid until it’s filled, or until you cancel it.
- FOK (fill or kill) – FOK instructs the exchange to execute an order all at once. If the exchange can’t do so, the order is immediately canceled.
- IOC (immediate or cancel) – either all or part of the order must be executed immediately, or it’s canceled. Unlike FOK, the orders are not canceled if they can be partially filled.
- quantity – simply, the quantity of the asset that you want to buy or sell.
- price – the price at which you want to sell. For the BTCUSDT pair, this is expressed in USDT.
- newClientOrderId – an identifier for the order. This isn’t a mandatory field, but you can set it to an identifier that will make it easy to query later. Otherwise, it is randomly generated by the exchange.
Place a real order
Time to place a real fake order.
Your response returns a bunch of details about the order if successful.
Check an open order’s status
We got confirmation that the order was placed in the previous section, but what if we want to check it again later? We have a few requests at our disposal.
Lastly, we can query specific orders with:
Cancel an order
After some time, we might decide that the $40,000 target is a little too optimistic, so we want to cancel it. In that case, we’d use:
Place an order that fills instantly
Below, you can see that we’re about to submit a market order to sell BNB for BUSD at the current market price.
Note that the response gives us minimal information:
Checking your trades
Let’s lastly look at the endpoint for checking your trades:
Debugging with Postman
In Postman, it’s possible to further reveal the raw HTTP request and response.
This menu will open the Postman console, which prints out the details of each request.
The purpose of this guide was to gently introduce you to the Binance API without writing a single line of code. If you’ve followed along, you should now have an idea of how we can request and submit information.