Making Sense of the SmartAPI Documentation

6 mins read
by Angel One

Hi There, Readers; we have noticed that many times, coming from a non-technical background, it can get difficult for people to navigate technical documents and forums like the SmartAPI documentation and forum. While we look at user feedback daily and improve our docs, we realize that it might not be really straightforward for everyone to understand. So in this article, we will help you make sense of what each section of the SmartAPI Docs means.

SmartAPI Documentation

The relevance of any technical documentation is to give the developers a single document to refer to if they have any doubts about how the API will be working, what kind of requests they are allowed to make, how many requests per second they can make. This documentation should be treated as a golden source of data compared to anything else referring to SmartAPI over the internet. We have tried to simplify this for you, but we will briefly explain what each of the below-highlighted sections does.

Introduction

What exactly is an API?

Think of API as a gateway, your gateway to collect information, or your gateway to send information.  For example, consider a supermarket consisting of multiple sections, if you want to buy clothes, you go to the clothing section, if you want to buy cooking oil, you go to the food section, similarly if you want to redeem your gift voucher, you go to the billing section. Now, all these sections act as a gateway for you, and similarly that way, an API allows you to fetch your margin balances, place orders, modify orders, etc.

Libraries and SDKs

Software Development Kits are very useful to developers as well; let’s assume you are in a Thai supermarket and you do not speak Thai, you take the help of a local guide who interacts with different people/sections of the supermarket to get what you need in the most efficient manner possible. Your local guide is now acting as an SDK for you. Angel One team has made you available SDKs in multiple languages. You can use what you like to create your rule-based strategy without worrying about dealing with each and every gateway of the API. You can find all our SDKs on this Github Page.

Response Structure

This section in the docs demonstrates the request’s response via API or SDK; the response is always received in JSON format, which is a very standard data format in the programming world. The docs show examples of how a successful and failed API call response will look like. If you use an SDK to reach the gateways, you need not worry about the header parameters.

Error Codes

Errors happen; as much as we try to prevent them, they do happen. When using SmartAPI or any of the SDKs, if your request does not contain all the parameters it needs to process information or contains incorrect information (like wrong password, wrong ticker), you will get an error code. This page tells you what each error code means.

User

This page shows code examples in multiple languages like Python, NodeJS, Go, Java, R if you are directly using the API endpoint. However, we recommend you to use the SDKs, which will make your life much easier if you are a newbie coder. You will get examples of how to log in, authenticate yourself on Angel One servers, and then show you how to log out.

GTT (Good Till Triggered)

SmartAPI gives you the power to place GTT orders on the NSE & BSE exchange in the DELIVERY and MARGIN segment. GTT orders are very useful when you want to place a long-term order which you do not have to monitor every day; it triggers and enters into a position as soon as your price is met. This section of the docs gives you code examples of creating new GTT rules, modifying, and even canceling them.

Orders

The most widely used feature in our SmartAPI is the Orders endpoint. The docs will provide you code examples and response structure on how to place, modify, cancel orders in your brokerage account via APIs. You can also get a list of all trades you have placed for the day via the orders endpoint. It will also allow you to fetch the LTP (Last Traded Price) of any symbol you pass through it.

Portfolio

This endpoint provides you all the information about the portfolio you hold with Angel One. The docs give you an example of how to fetch all your holdings, positions and even gives you the option of converting any of your existing positions to a different product type (Like INTRADAY to DELIVERY); in the next article, we will show you some examples of this using the Python SDK.

Postback

When you place an order via the APIs or SDKs, you get a JSON response with your Order ID. The Postback feature (if you have it enabled) allows you to receive the complete order response on the Postback URL you may have provided when generating the API Key. This is not a mandatory thing to do but gives you the sample response if you wish to set it up.

Historical API

Again a very famous endpoint amongst SmartAPI users, this section provides you with the sample code in different languages on fetching the historical data for all stocks on the NSE segment and NFO Futures via the APIs. We will be using the Python SDK to show you how you can use this feature in our future article. So stay tuned!

Publisher JS Plugin

This section is useful for readers who want to generate dynamic buttons for their clients who can execute orders and even buy/sell baskets of stocks on Angel One in a single click. This is in Javascript language, and can these buttons can be embedded onto your website/mobile app/telegram chatbots and others. The docs will give you sample codes for different types of buttons.

Websocket Streaming

Websockets (WSS) is basically a connection between us and the broker servers where we request the continuous stock prices information to the server. It responds with a continuous stream of prices until the broker or client stops the connection. This page in the docs shows how you can use the API endpoint to get a stream of live prices and run them through your rule-based strategy to generate orders to place. We will soon be having an article on How to use Websockets via the Python SDKs.

Websocket Order Status

Quite often in the markets, when you place a LIMIT or a STOPLOSS order, it might not execute immediately if your price condition has not been met. To keep track of such orders, users can utilize this section of the docs to subscribe for order feeds to get notified immediately when your order executes or gets canceled.

Instruments

As you know, IPOs happen all the time, and not only IPOs, new options, and future expiries come periodically as well, SmartAPI allows you to fetch this latest list of instruments in a programmable manner so you can run them in your strategies. The docs show you an example of how to fetch this list; you can also visit this link to check out what the JSON structured data looks like.

Rate Limit

To provide the best service to all our SmartAPI users equally, we restrict the number of API requests one user can make every second, this page in the docs give you the rate limits; for example, you cannot make more than 10 order requests in 1 second, but that is still 600 order requests every minute. This is a very generous limit as compared to other brokers in the industry.

ChangeLog

We evolve the SmartAPI over time to be better, robust, and faster. This page in the docs will give you all the changes we make to the APIs.

As again, we are committed to your journey in getting better with rule-based trading, so if you have any suggestions or feedback for us or want us to cover any specific blog, please let us know in responses below, and we will be happy to do so.

Disclaimer: ‘Investments in securities market are subject to market risk, read all the related documents carefully before investing.’