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:

  1. Navigate to the Kite Connect login page with the api_key
  2. A succesful login comes back with a request_token to the registered redirect URL
  3. POST the request_token and checksum (SHA-256 of api_key + request_token + api_secret) to /session/token
  4. 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.

Kite Connect handshake flow

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_idstring The unique, peramanent user id registered with the broker and the exchanges
user_namestring User's real name
user_shortnamestring Shortened version of the user's real name
emailstring User's email
user_typestring User's registered role at the broker. This will be investor for all retail users
brokerstring The broker ID
exchangesstring[] Exchanges enabled for trading on the user's account
productsstring[] Margin product types enabled for the user
order_typesstring[] Order types enabled for the user
api_keystring The API key for which the authentication was performed
access_tokenstring 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_tokenstring A token for public session validation where requests may be exposed to the public
refresh_tokenstring A token for getting long standing read permissions. This is only available to certain approved platforms
login_timestring User's last login time
avatar_urlstring 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  
enabledbool Indicates whether the segment is enabled for the user
netfloat Net cash balance available for trading (intraday_payin + adhoc_margin + collateral)
available.cashfloat Raw cash balance in the account available for trading (also includes intraday_payin)
available.intraday_payinfloat Amount that was deposited during the day
available.adhoc_marginfloat Additional margin provided by the broker
available.collateralfloat Margin derived from pledged stocks
utilised.m2m_unrealisedfloat Un-booked (open) intraday profits and losses
utilised.m2m_realisedfloat Booked intraday profits and losses
utilised.debitsfloat Sum of all utilised margins (unrealised M2M + realised M2M + SPAN + Exposure + Premium + Holding sales)
utilised.spanfloat SPAN margin blocked for all open F&O positions
utilised.option_premiumfloat Value of options premium received by shorting
utilised.holding_salesfloat Value of holdings sold during the day
utilised.exposurefloat Exposure margin blocked for all open F&O positions
utilised.turnoverfloat Utilised portion of the maximum turnover limit (only applicable to certain clients)
utilised.payoutfloat Funds paid out 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"