How to debug and manually work in an automated world
When it comes to writing any software, let alone automated stock trading solutions, I like to double check my code. With APIs, this means having a tool that is able to make the API request and return the response.
Often we put integration tests into our software and run them against a sandbox or testing environment. Alpaca’s API does indeed provide such an environment — it’s called paper trading.
I can make requests against the paper trading API while developing my application and not worry about paying for my mistakes.
Before I even get started though, I want to see how it all works. Somewhere after documentation but before code. To make these requests I could use the command line and cURL. It lacks some creature comforts though so many developers reach for RESTful API clients such as Insomnia or Postman (among others).
I used Insomnia, organized all of the API requests into folders, set up an environment with variables to use and override when using the live or paper trading API. This makes copying requests to create new adjusted ones easy and also allows me to switch between environments (brokerage services are offered through Alpaca Securities LLC).
The end result leaves me with a more beautiful than command line tool that I can double check my code against. Does my code see what I’m seeing myself? Great! If not, then it’s time to investigate and debug.
These tools are extremely valuable in debugging code and just figuring out what calls your code is going to make.
The other thing that’s nice here is that I can also make requests that quickly close out all of my positions or allow me to take other manual actions. Without having to write or copy and paste some lengthy command to my terminal, or write code, I can easily use Insomnia instead. This provides a great deal of flexibility between my applications and my own needs outside of the code.
How it Works
In the above screenshot you’ll see a basic Alpaca Data API request. Nothing fancy, but let’s take a look at what you’re looking at.
Alpaca
On the left hand side, I’ve added all of Alpaca’s API methods organized with folders.
In the center, you’ll see the request options including the body payload, headers, querystring parameters, and so on. These are going to be where you’ll want to adjust and add your own values to change the request.
Obviously, the right side has the response from the server. Should anything go wrong, you’ll see it here. You’ll also see error messages (and headers) from the server as well. Common errors here could include missing access keys or market closed messages if sending requests after hours. See the example below.
How to Use It
Do you have a free Alpaca account? Obviously you’ll need one of those along with API keys to use this. It’s quick and easy to sign up and login. Generate free paper trading API keys if you haven’t done so already.
To get started, you’ll want to download and install Insomnia if you don’t have it already. Next, download the Workspace export file (JSON) from the GitHub repository here. The releases section has a zip file you can download, so there’s no need for git. Just extract the zip file on your computer.
Then import it into Insomnia from the Workspace menu (that white down arrow/triangle in the big purple area) and to go “Import/Export.” Find the JSON file you just downloaded on your computer (in this case it’s called Alpaca-API_2018–12–12.json but if there’s a newer version the date would be different). See the screenshot below.
Before being able to make requests, you’ll want adjust some Workspace environment variables to include your own API access keys. There will be two potential places to do this; the Paper Trading environment and the Live Trading environment. It depends on which API you’re looking to use.
Using the environment menu (which may say “No Environment” by default), open the drop-down menu and click “Manage Environments.” You’ll be able to adjust the variables in each environment. The most relevant thing here is putting in your access keys. Some placeholder text has been left in place to help guide you.
Note: Insomnia does not encrypt these values in any way. Take appropriate care when working with Insomnia.
You’ll also see the Base Environment. This holds all of the variables whereas the sub environments replace them. So you’ll see the API key, secret, and sub domain overriding the base values for each environment. For reference, there’s a screenshot of what’s in the base environment below.
You should be all set now! Before, you make requests, it’s wise to start with the paper trading environment first.
Making Requests
Making the requests should be fairly straight forward just by looking at it here. However, you’re going to need to understand a little bit about Insomnia’s variables and workspaces.
See the “app_url” text with purple background in the screenshot above? That’s an environment variable and it changes based on whether you’ve chosen the“Paper Trading” or “Live Trading” environment (also seen in the screenshot; to the left above the request list).
Make the “Get Account Info” request first as it won’t harm anything. You should see your account balance, status, and some other information.
Take a look at the other requests on the left hand side of the application. They reflect what you’ll find in the API docs. There’s even some documentation included here in Insomnia (though it’s not able to be synced to our official documentation).
The GitHub repo will do its best to include timely updates Insomnia Workspace as Alpaca’s API changes (please feel free to send pull requests too!). However, the moment you begin to add your own requests you essentially fork the Workspace. So you will not be able to apply any updates or anything like that.
Do not accidentally export and share your workspace. Instead, import the one from the repository and rename it to something you will remember.
Therefore, you’ll want to go to Workspace Settings and change the name to something meaningful to you. Then if you import an updated version, it’ll be kept separate and you can copy over requests.
Helper Variables
Included are some environment variables designed to help you fill common request parameters. For example, when placing orders, the “side” will be either “buy” or “sell.” You could just type that text, or you could start typing “side” and use Insomnia’s autocomplete. This can help save you some time and avoid flipping a window to reference the documentation. See the screenshot below.
Try Placing a Paper Order
For this to work, the market will need to be open. Even though this is just paper trading, the quotes and simulation is based on real-time data. Alpaca’s paper API mimics the live API and so requests are bound to the same rules.
Using the “Orders” > “Place Buy Order” request, update the JSON body to include the “symbol” and “qty” you’d like to purchase. Add any additional options such as limit price. When ready, click “Send.”
Congratulations! You just placed a paper order. You could see it by issuing the “List All Orders” request.
What’s Next?
Explore the other requests while in the Paper Trading environment. It’s a really great way to learn about Alpaca’s API and also debug your applications when you’re ready.
Take a look at your Alpaca Dashboard and you’ll see your API requests reflected there as well. The dashboard includes a great overview so you don’t need to solely rely upon JSON responses or code.
Technology and services are offered by AlpacaDB, Inc. Brokerage services are provided by Alpaca Securities LLC (alpaca.markets), member FINRA/SIPC. Alpaca Securities LLC is a wholly-owned subsidiary of AlpacaDB, Inc.
You can find us @AlpacaHQ, if you use twitter.