Understanding and using an API for cryptocurrency trading can open up a world of possibilities when it comes to entering and exiting positions. With some simple coding knowledge, you can plug into an exchange’s backend to automate your trading strategies. By sidestepping the website, you can take a much faster path to the matching engine for high-performance applications.
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.
In this article, we’ll be using Postman to communicate with the exchange. Don’t worry – we won’t be putting any real funds at risk.
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.
Note: labelling your keys is something worth doing when using the real exchange in order to manage different keys. Your account can have multiple keys with different permissions. If you’re running several trading bots, using separate keys with descriptive labels makes it easier to manage permissions or delete individual keys without changing all of your bots.
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.
The program is available for Mac, Windows, and Linux. Head over to the Downloads page and download the .zip file.
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.
At this stage, you should have an interface that resembles the following.
We want to first create our environment. This is just a way for us to add variables to the set of requests we’re going to work with. To do that, we’ll first need to grab some information from the Binance GitHub repository. Head over here and download the .zip file.
The download shouldn’t take very long. Find it in your file explorer and unzip it. Then, we can head back into Postman.
Click on the gear icon in the top right-hand corner (illustrated above). You’ll be greeted with a Manage Environments popup.
Almost there. Click on Binance Spot Testnet API, and you’ll see the variables below. Edit the two parameters outlined in red by pasting in the keys you saved earlier. Click update and exit out of the popup.
On this screen, leave the timestamp and signature fields blank. These two values will be automatically created upon each request.
There’s one last thing to do. To the right of the gear icon we clicked to set up the environment earlier, you’ll see a dropdown menu that currently says No Environment. Click it and select Binance Spot Testnet API.
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:
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:
Time for our first request! We’re going to get the symbols we can trade on the exchange and the trading rules:
GET /exchangeInfo
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.
To load up this request, select Market > Exchange Information. A tab like the following will pop up:
We don’t need to do anything else here, so go ahead and hit Send. You’ll then get a response:
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.
Let’s check what assets we have, and how much of each:
GET /account
This one can be found under Trade > Account Information. Click on it, and you’ll see a similar layout to the previous one. You’ll also note, however, that we have two new variables: timestamp and signature. The signature is a security measure. Because we’re now asking for sensitive information, it will prove that we’re the account holder.
The timestamp tells the server when the request was sent. Because networks can be unreliable or face downtime, the server might receive our request much later than intended. If too much time has passed, it will reject the request. You can specify how long you want to wait with the recvWindow parameter, which defaults to 5000 milliseconds.
Postman handles the generation of both of these fields for us. Click send, and you’ll get a response. Under balances, you should see six assets – BNB, BTC, BUSD, ETH, LTC, and TRX. The balance will be split across free and locked. We haven’t locked any up yet, so your assets should all be free.
Congratulations on your newfound (non-existent) wealth!
We can go about getting the current price of an asset in different ways. Perhaps the simplest is with the following request:
GET /api/v3/ticker/24hr
As you might guess, this will give us information about asset prices from the past twenty-four hours. Find it in Market > 24hr Ticker Price Change Statistics. The default pair we’re greeted with as the symbol variable is BTCUSDT.
You can send this straight away to see a breakdown of price information. You can also change the symbol (to BNBBUSD, LTCUSDT, etc.), or you can uncheck the variable to return data for 40 pairs.
We also have a simpler call (Market > Symbol Price Ticker) that returns the current price that an asset is trading at:
GET /api/v3/price
As with the previous, you can change the symbol variable or remove it completely and get the latest price for all symbols.
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:
GET api/v3/depth
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.
Keep scrolling, and you’ll see the asks. They’re functionally similar to bids, except they represent orders to sell BTC for USDT.
Now we’re going to post a test order.
POST api/v3/order/test
Even though we’re just using testnet funds, this request won’t actually place an order. It can come in useful for testing orders before actually submitting them. Find it under Trade > Test New Order (TRADE).
You can see we have many more parameters involved. Let’s walk through the checked ones:
Okay! Let’s create a test order now. We’re going to go with the automatically-generated values: a limit order to sell 0.1 BTC for USDT at $9000. Hit Send. If this was successful, then we’ll simply get {} as a response.
Time to place a real fake order.
POST /api/v3/order
Navigate to Trade > New Order. You’re familiar with test orders by now, so the parameters here will come as no surprise. Let’s leave all the values as they are, but since we’re permabulls, we’ll change the price that we’re selling at to $40,000. Tweak the price value to reflect this. Then, hit Send.
Your response returns a bunch of details about the order if successful.
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.
GET /api/v3/openOrders
You’ll find this in Trade > Current Open Orders (USER_DATA). BTCUSDT is selected by default. If you hit Send, you’ll get all of your open BTCUSDT orders (so far, you should only see the one we set previously). You can choose not to specify a symbol, which will return all of your open orders instead.
GET /api/v3/allOrders
Trade > All Orders (USER_DATA) gives you an overview of all orders – not just open ones. Here, you must provide a symbol. orderId, startTime, endTime, and limit are optional parameters that can help you refine your search. We’ll leave them out here, so uncheck them. Hit Send, and you’ll see the same response as before. If you had any closed or canceled orders, you’d see them here too.
Lastly, we can query specific orders with:
GET /api/v3/order
Get this under Trade > Query Order (USER_DATA). You’ll need to provide either the orderId or the origClientOrderId (the optional tag “newClientOrderId” you can add to orders). Uncheck orderId. For origClientOrderId, we’re going to provide the default tag from earlier – ”my_order_id_1”. Fill in the field and hit Send to get the response.
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:
DELETE /api/v3/order
Under Trade > Cancel Order is a request that will allow us to single out orders for cancelation. Uncheck orderId and newClientOrderId and pass “my_order_id_1” as the value for origClientOrderId.
When you send this request, the order will be returned. If you scroll down to “status,” you’ll see that it’s indeed canceled. To confirm this, use the GET /api/v3/openOrders endpoint again (giving you an empty list) or GET /api/v3/order with the origClientOrderId.
Our previous order wasn’t filled because it was a limit order that would only trigger when the BTC price hit $40,000. With a market order, we’re basically saying “buy/sell at whatever price the asset is currently trading at.” This will fill instantly.
For that, let’s head back to Trade > New Order. We’re going to demonstrate the response type (newOrderRespType), which is a parameter we can tweak depending on the response we want to get from the server. There are three options here: ACK, RESULT, or FULL – you can see examples of each response here. We’re going to go with ACK, which will give us a simple acknowledgment that the order was received.
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:
You can verify that the order was filled with the /api/v3/allOrders endpoint.
Let’s lastly look at the endpoint for checking your trades:
GET /api/v3/myTrades
This is located under Trade > Account Trade List (USER_DATA). It allows you to check each trade for a particular symbol. If you want to see all of your trades for the default symbol (BTCUSDT), simply uncheck startTime, endTime and fromId. The response will return up to 500 trades – simply tweak the limit if you want to see more.
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.
In the next installments in this series, we’ll introduce some basic coding concepts that allow us to automate the buying and selling of cryptocurrencies and other digital assets.
Questions in the meantime? Head over to our growing Binance Developer Community forum, or take a look at the documentation.