User¶
Login flow¶
The login flow starts by navigating to the public Kite login endpoint.
https://kite.zerodha.com/connect/login?v=3&api_key=xxx
A successful login comes back with a request_token
as a URL query parameter to the redirect URL registered on the developer console for that api_key
. This request_token
, along with a checksum
(SHA-256 of api_key + request_token + api_secret
) is POSTed to the token API to obtain an access_token
, which is then used for signing all subsequent requests. In summary:
- Navigate to the Kite Connect login page with the api_key
- A succesful login comes back with a
request_token
to the registered redirect URL - POST the
request_token
andchecksum
(SHA-256 ofapi_key + request_token + api_secret
) to/session/token
- Obtain the
access_token
and use that with all subsequent requests
An optional
redirect_params
param can be appended to public Kite login endpoint, that will be sent back to the redirect URL. The value is URL encoded query params string, eg:some=X&more=Y
). eg:https://kite.zerodha.com/connect/login?v=3&api_key=xxx&redirect_params=some%3DX%26more%3DY
Here's a webinar that shows the login flow and other interactions.
Warning
Never expose your api_secret
by embedding it in a mobile app or a client side application. Do not expose the access_token
you obtain for a session to the public either.
type | endpoint | |
---|---|---|
POST | /session/token | Authenticate and obtain the access_token after the login flow |
GET | /user/profile | Retrieve the user profile |
GET | /user/margins/:segment | Retrieve detailed funds and margin information |
DELETE | /session/token | Logout and invalidate the API session and access_token |
Authentication and token exchange¶
Once the request_token
is obtained from the login flow, it should be POSTed to /session/token
to complete the token exchange and retrieve the access_token
.
curl https://api.kite.trade/session/token \ -H "X-Kite-Version: 3" \ -d "api_key=xxx" \ -d "request_token=yyy" \ -d "checksum=zzz"
{ "status": "success", "data": { "user_id": "XX000", "user_name": "Kite Connect", "user_shortname": "Kite", "email": "[email protected]", "user_type": "investor", "broker": "ZERODHA", "exchanges": [ "MCX", "BSE", "NSE", "BFO", "NFO", "CDS" ], "products": [ "BO", "CNC", "CO", "MIS", "NRML" ], "order_types": [ "LIMIT", "MARKET", "SL", "SL-M" ], "api_key": "xxxxxx", "access_token": "yyyyyy", "public_token": "zzzzzz", "refresh_token": null, "login_time": "2018-01-01 16:15:14", "avatar_url": null } }
Request parameters¶
parameter | |
---|---|
api_key |
The public API key |
request_token |
The one-time token obtained after the login flow. This token's lifetime is only a few minutes and it is meant to be exchanged for an access_token immediately after being obtained |
checksum |
SHA-256 hash of (api_key + request_token + api_secret) |
Response attributes¶
attribute | |
---|---|
user_id string |
The unique, peramanent user id registered with the broker and the exchanges |
user_name string |
User's real name |
user_shortname string |
Shortened version of the user's real name |
email string |
User's email |
user_type string |
User's registered role at the broker. This will be investor for all retail users |
broker string |
The broker ID |
exchanges string[] |
Exchanges enabled for trading on the user's account |
products string[] |
Margin product types enabled for the user |
order_types string[] |
Order types enabled for the user |
api_key string |
The API key for which the authentication was performed |
access_token string |
The authentication token that's used to be used with every subsequent request. Unless this is invalidated using the API, or invalidated by a master-logout from the Kite Web trading terminal, it'll expire at 6 AM on the next day (regulatory requirement) |
public_token string |
A token for public session validation where requests may be exposed to the public |
refresh_token string |
A token for getting long standing read permissions. This is only available to certain approved platforms |
login_time string |
User's last login time |
avatar_url string |
Full URL to the user's avatar (PNG image) if there's one |
Signing requests¶
Once the authentication is complete, all requests should be signed with the HTTP Authorization
header with token
as the authorisation scheme, followed by a space, and then the api_key:access_token
combination. For example:
curl -H "Authorization: token api_key:access_token" curl -H "Authorization: token xxx:yyy"
User profile¶
While a successful token exchange returns the full user profile, it's possible to retrieve it any point of time with the /user/profile
API. Do note that the profile API does not return any of the tokens.
curl https://api.kite.trade/user/profile \ -H "X-Kite-Version: 3" \ -d "api_key=xxx" \ -d "request_token=yyy"
{ "status": "success", "data": { "user_type": "investor", "email": "[email protected]", "user_name": "Kite Connect", "user_shortname": "Kite", "broker": "ZERODHA", "exchanges": [ "MCX", "BSE", "NSE", "BFO", "NFO", "CDS" ], "products": [ "BO", "CNC", "CO", "MIS", "NRML" ], "order_types": [ "LIMIT", "MARKET", "SL", "SL-M" ] } }
Funds and margins¶
A GET request to /user/margins
returns funds, cash, and margin information for the user for equity and commodity segments.
A GET request to /user/margins/:segment
returns funds, cash, and margin information for the user. segment
in the URI can be either equity
or commodity
.
curl "https://api.kite.trade/user/margins" \ -H "X-Kite-Version: 3" \ -H 'Authorization: token api_key:access_token'
{ "status": "success", "data": { "equity": { "enabled": true, "net": 24966.7493, "available": { "adhoc_margin": 0, "cash": 25000, "collateral": 0, "intraday_payin": 0 }, "utilised": { "debits": 33.2507, "exposure": 0, "m2m_realised": -0.25, "m2m_unrealised": 0, "option_premium": 0, "payout": 0, "span": 0, "holding_sales": 0, "turnover": 0 } }, "commodity": { "enabled": true, "net": 25000, "available": { "adhoc_margin": 0, "cash": 25000, "collateral": 0, "intraday_payin": 0 }, "utilised": { "debits": 0, "exposure": 0, "m2m_realised": 0, "m2m_unrealised": 0, "option_premium": 0, "payout": 0, "span": 0, "holding_sales": 0, "turnover": 0 } } } }
Response attributes¶
attribute | |
---|---|
enabled bool |
Indicates whether the segment is enabled for the user |
net float |
Net cash balance available for trading (intraday_payin + adhoc_margin + collateral ) |
available.cash float |
Raw cash balance in the account available for trading (also includes intraday_payin ) |
available.intraday_payin float |
Amount that was deposited during the day |
available.adhoc_margin float |
Additional margin provided by the broker |
available.collateral float |
Margin derived from pledged stocks |
utilised.m2m_unrealised float |
Un-booked (open) intraday profits and losses |
utilised.m2m_realised float |
Booked intraday profits and losses |
utilised.debits float |
Sum of all utilised margins (unrealised M2M + realised M2M + SPAN + Exposure + Premium + Holding sales) |
utilised.span float |
SPAN margin blocked for all open F&O positions |
utilised.option_premium float |
Value of options premium received by shorting |
utilised.holding_sales float |
Value of holdings sold during the day |
utilised.exposure float |
Exposure margin blocked for all open F&O positions |
utilised.turnover float |
Utilised portion of the maximum turnover limit (only applicable to certain clients) |
utilised.payout float |
Funds paid our or withdrawn to bank account during the day |
Logout¶
This call invalidates the access_token and destroys the API session. After this, the user should be sent through a new login flow before further interactions. This does not log the user out of the official Kite web or mobile applications.
curl --request DELETE \ -H "X-Kite-Version: 3" \ "https://api.kite.trade/session/token?api_key=xxx&access_token=yyy"