kiteconnect

 28class KiteConnect(object):
 29    """
 30    The Kite Connect API wrapper class.
 31
 32    In production, you may initialise a single instance of this class per `api_key`.
 33    """
 34
 35    # Default root API endpoint. It's possible to
 36    # override this by passing the `root` parameter during initialisation.
 37    _default_root_uri = "https://api.kite.trade"
 38    _default_login_uri = "https://kite.zerodha.com/connect/login"
 39    _default_timeout = 7  # In seconds
 40
 41    # Kite connect header version
 42    kite_header_version = "3"
 43
 44    # Constants
 45    # Products
 46    PRODUCT_MIS = "MIS"
 47    PRODUCT_CNC = "CNC"
 48    PRODUCT_NRML = "NRML"
 49    PRODUCT_CO = "CO"
 50
 51    # Order types
 52    ORDER_TYPE_MARKET = "MARKET"
 53    ORDER_TYPE_LIMIT = "LIMIT"
 54    ORDER_TYPE_SLM = "SL-M"
 55    ORDER_TYPE_SL = "SL"
 56
 57    # Varities
 58    VARIETY_REGULAR = "regular"
 59    VARIETY_CO = "co"
 60    VARIETY_AMO = "amo"
 61    VARIETY_ICEBERG = "iceberg"
 62    VARIETY_AUCTION = "auction"
 63
 64    # Transaction type
 65    TRANSACTION_TYPE_BUY = "BUY"
 66    TRANSACTION_TYPE_SELL = "SELL"
 67
 68    # Validity
 69    VALIDITY_DAY = "DAY"
 70    VALIDITY_IOC = "IOC"
 71    VALIDITY_TTL = "TTL"
 72
 73    # Position Type
 74    POSITION_TYPE_DAY = "day"
 75    POSITION_TYPE_OVERNIGHT = "overnight"
 76
 77    # Exchanges
 78    EXCHANGE_NSE = "NSE"
 79    EXCHANGE_BSE = "BSE"
 80    EXCHANGE_NFO = "NFO"
 81    EXCHANGE_CDS = "CDS"
 82    EXCHANGE_BFO = "BFO"
 83    EXCHANGE_MCX = "MCX"
 84    EXCHANGE_BCD = "BCD"
 85
 86    # Margins segments
 87    MARGIN_EQUITY = "equity"
 88    MARGIN_COMMODITY = "commodity"
 89
 90    # Status constants
 91    STATUS_COMPLETE = "COMPLETE"
 92    STATUS_REJECTED = "REJECTED"
 93    STATUS_CANCELLED = "CANCELLED"
 94
 95    # GTT order type
 96    GTT_TYPE_OCO = "two-leg"
 97    GTT_TYPE_SINGLE = "single"
 98
 99    # GTT order status
100    GTT_STATUS_ACTIVE = "active"
101    GTT_STATUS_TRIGGERED = "triggered"
102    GTT_STATUS_DISABLED = "disabled"
103    GTT_STATUS_EXPIRED = "expired"
104    GTT_STATUS_CANCELLED = "cancelled"
105    GTT_STATUS_REJECTED = "rejected"
106    GTT_STATUS_DELETED = "deleted"
107
108    # URIs to various calls
109    _routes = {
110        "api.token": "/session/token",
111        "api.token.invalidate": "/session/token",
112        "api.token.renew": "/session/refresh_token",
113        "user.profile": "/user/profile",
114        "user.margins": "/user/margins",
115        "user.margins.segment": "/user/margins/{segment}",
116
117        "orders": "/orders",
118        "trades": "/trades",
119
120        "order.info": "/orders/{order_id}",
121        "order.place": "/orders/{variety}",
122        "order.modify": "/orders/{variety}/{order_id}",
123        "order.cancel": "/orders/{variety}/{order_id}",
124        "order.trades": "/orders/{order_id}/trades",
125
126        "portfolio.positions": "/portfolio/positions",
127        "portfolio.holdings": "/portfolio/holdings",
128        "portfolio.holdings.auction": "/portfolio/holdings/auctions",
129        "portfolio.positions.convert": "/portfolio/positions",
130
131        # MF api endpoints
132        "mf.orders": "/mf/orders",
133        "mf.order.info": "/mf/orders/{order_id}",
134        "mf.order.place": "/mf/orders",
135        "mf.order.cancel": "/mf/orders/{order_id}",
136
137        "mf.sips": "/mf/sips",
138        "mf.sip.info": "/mf/sips/{sip_id}",
139        "mf.sip.place": "/mf/sips",
140        "mf.sip.modify": "/mf/sips/{sip_id}",
141        "mf.sip.cancel": "/mf/sips/{sip_id}",
142
143        "mf.holdings": "/mf/holdings",
144        "mf.instruments": "/mf/instruments",
145
146        "market.instruments.all": "/instruments",
147        "market.instruments": "/instruments/{exchange}",
148        "market.margins": "/margins/{segment}",
149        "market.historical": "/instruments/historical/{instrument_token}/{interval}",
150        "market.trigger_range": "/instruments/trigger_range/{transaction_type}",
151
152        "market.quote": "/quote",
153        "market.quote.ohlc": "/quote/ohlc",
154        "market.quote.ltp": "/quote/ltp",
155
156        # GTT endpoints
157        "gtt": "/gtt/triggers",
158        "gtt.place": "/gtt/triggers",
159        "gtt.info": "/gtt/triggers/{trigger_id}",
160        "gtt.modify": "/gtt/triggers/{trigger_id}",
161        "gtt.delete": "/gtt/triggers/{trigger_id}",
162
163        # Margin computation endpoints
164        "order.margins": "/margins/orders",
165        "order.margins.basket": "/margins/basket"
166    }
167
168    def __init__(self,
169                 api_key,
170                 access_token=None,
171                 root=None,
172                 debug=False,
173                 timeout=None,
174                 proxies=None,
175                 pool=None,
176                 disable_ssl=False):
177        """
178        Initialise a new Kite Connect client instance.
179
180        - `api_key` is the key issued to you
181        - `access_token` is the token obtained after the login flow in
182            exchange for the `request_token` . Pre-login, this will default to None,
183        but once you have obtained it, you should
184        persist it in a database or session to pass
185        to the Kite Connect class initialisation for subsequent requests.
186        - `root` is the API end point root. Unless you explicitly
187        want to send API requests to a non-default endpoint, this
188        can be ignored.
189        - `debug`, if set to True, will serialise and print requests
190        and responses to stdout.
191        - `timeout` is the time (seconds) for which the API client will wait for
192        a request to complete before it fails. Defaults to 7 seconds
193        - `proxies` to set requests proxy.
194        Check [python requests documentation](http://docs.python-requests.org/en/master/user/advanced/#proxies) for usage and examples.
195        - `pool` is manages request pools. It takes a dict of params accepted by HTTPAdapter as described here in [python requests documentation](http://docs.python-requests.org/en/master/api/#requests.adapters.HTTPAdapter)
196        - `disable_ssl` disables the SSL verification while making a request.
197        If set requests won't throw SSLError if its set to custom `root` url without SSL.
198        """
199        self.debug = debug
200        self.api_key = api_key
201        self.session_expiry_hook = None
202        self.disable_ssl = disable_ssl
203        self.access_token = access_token
204        self.proxies = proxies if proxies else {}
205
206        self.root = root or self._default_root_uri
207        self.timeout = timeout or self._default_timeout
208
209        # Create requests session by default
210        # Same session to be used by pool connections
211        self.reqsession = requests.Session()
212        if pool:
213            reqadapter = requests.adapters.HTTPAdapter(**pool)
214            self.reqsession.mount("https://", reqadapter)
215
216        # disable requests SSL warning
217        requests.packages.urllib3.disable_warnings()
218
219    def set_session_expiry_hook(self, method):
220        """
221        Set a callback hook for session (`TokenError` -- timeout, expiry etc.) errors.
222
223        An `access_token` (login session) can become invalid for a number of
224        reasons, but it doesn't make sense for the client to
225        try and catch it during every API call.
226
227        A callback method that handles session errors
228        can be set here and when the client encounters
229        a token error at any point, it'll be called.
230
231        This callback, for instance, can log the user out of the UI,
232        clear session cookies, or initiate a fresh login.
233        """
234        if not callable(method):
235            raise TypeError("Invalid input type. Only functions are accepted.")
236
237        self.session_expiry_hook = method
238
239    def set_access_token(self, access_token):
240        """Set the `access_token` received after a successful authentication."""
241        self.access_token = access_token
242
243    def login_url(self):
244        """Get the remote login url to which a user should be redirected to initiate the login flow."""
245        return "%s?api_key=%s&v=%s" % (self._default_login_uri, self.api_key, self.kite_header_version)
246
247    def generate_session(self, request_token, api_secret):
248        """
249        Generate user session details like `access_token` etc by exchanging `request_token`.
250        Access token is automatically set if the session is retrieved successfully.
251
252        Do the token exchange with the `request_token` obtained after the login flow,
253        and retrieve the `access_token` required for all subsequent requests. The
254        response contains not just the `access_token`, but metadata for
255        the user who has authenticated.
256
257        - `request_token` is the token obtained from the GET paramers after a successful login redirect.
258        - `api_secret` is the API api_secret issued with the API key.
259        """
260        h = hashlib.sha256(self.api_key.encode("utf-8") + request_token.encode("utf-8") + api_secret.encode("utf-8"))
261        checksum = h.hexdigest()
262
263        resp = self._post("api.token", params={
264            "api_key": self.api_key,
265            "request_token": request_token,
266            "checksum": checksum
267        })
268
269        if "access_token" in resp:
270            self.set_access_token(resp["access_token"])
271
272        if resp["login_time"] and len(resp["login_time"]) == 19:
273            resp["login_time"] = dateutil.parser.parse(resp["login_time"])
274
275        return resp
276
277    def invalidate_access_token(self, access_token=None):
278        """
279        Kill the session by invalidating the access token.
280
281        - `access_token` to invalidate. Default is the active `access_token`.
282        """
283        access_token = access_token or self.access_token
284        return self._delete("api.token.invalidate", params={
285            "api_key": self.api_key,
286            "access_token": access_token
287        })
288
289    def renew_access_token(self, refresh_token, api_secret):
290        """
291        Renew expired `refresh_token` using valid `refresh_token`.
292
293        - `refresh_token` is the token obtained from previous successful login flow.
294        - `api_secret` is the API api_secret issued with the API key.
295        """
296        h = hashlib.sha256(self.api_key.encode("utf-8") + refresh_token.encode("utf-8") + api_secret.encode("utf-8"))
297        checksum = h.hexdigest()
298
299        resp = self._post("api.token.renew", params={
300            "api_key": self.api_key,
301            "refresh_token": refresh_token,
302            "checksum": checksum
303        })
304
305        if "access_token" in resp:
306            self.set_access_token(resp["access_token"])
307
308        return resp
309
310    def invalidate_refresh_token(self, refresh_token):
311        """
312        Invalidate refresh token.
313
314        - `refresh_token` is the token which is used to renew access token.
315        """
316        return self._delete("api.token.invalidate", params={
317            "api_key": self.api_key,
318            "refresh_token": refresh_token
319        })
320
321    def margins(self, segment=None):
322        """Get account balance and cash margin details for a particular segment.
323
324        - `segment` is the trading segment (eg: equity or commodity)
325        """
326        if segment:
327            return self._get("user.margins.segment", url_args={"segment": segment})
328        else:
329            return self._get("user.margins")
330
331    def profile(self):
332        """Get user profile details."""
333        return self._get("user.profile")
334
335    # orders
336    def place_order(self,
337                    variety,
338                    exchange,
339                    tradingsymbol,
340                    transaction_type,
341                    quantity,
342                    product,
343                    order_type,
344                    price=None,
345                    validity=None,
346                    validity_ttl=None,
347                    disclosed_quantity=None,
348                    trigger_price=None,
349                    iceberg_legs=None,
350                    iceberg_quantity=None,
351                    auction_number=None,
352                    tag=None):
353        """Place an order."""
354        params = locals()
355        del (params["self"])
356
357        for k in list(params.keys()):
358            if params[k] is None:
359                del (params[k])
360
361        return self._post("order.place",
362                          url_args={"variety": variety},
363                          params=params)["order_id"]
364
365    def modify_order(self,
366                     variety,
367                     order_id,
368                     parent_order_id=None,
369                     quantity=None,
370                     price=None,
371                     order_type=None,
372                     trigger_price=None,
373                     validity=None,
374                     disclosed_quantity=None):
375        """Modify an open order."""
376        params = locals()
377        del (params["self"])
378
379        for k in list(params.keys()):
380            if params[k] is None:
381                del (params[k])
382
383        return self._put("order.modify",
384                         url_args={"variety": variety, "order_id": order_id},
385                         params=params)["order_id"]
386
387    def cancel_order(self, variety, order_id, parent_order_id=None):
388        """Cancel an order."""
389        return self._delete("order.cancel",
390                            url_args={"variety": variety, "order_id": order_id},
391                            params={"parent_order_id": parent_order_id})["order_id"]
392
393    def exit_order(self, variety, order_id, parent_order_id=None):
394        """Exit a CO order."""
395        return self.cancel_order(variety, order_id, parent_order_id=parent_order_id)
396
397    def _format_response(self, data):
398        """Parse and format responses."""
399
400        if type(data) == list:
401            _list = data
402        elif type(data) == dict:
403            _list = [data]
404
405        for item in _list:
406            # Convert date time string to datetime object
407            for field in ["order_timestamp", "exchange_timestamp", "created", "last_instalment", "fill_timestamp", "timestamp", "last_trade_time"]:
408                if item.get(field) and len(item[field]) == 19:
409                    item[field] = dateutil.parser.parse(item[field])
410
411        return _list[0] if type(data) == dict else _list
412
413    # orderbook and tradebook
414    def orders(self):
415        """Get list of orders."""
416        return self._format_response(self._get("orders"))
417
418    def order_history(self, order_id):
419        """
420        Get history of individual order.
421
422        - `order_id` is the ID of the order to retrieve order history.
423        """
424        return self._format_response(self._get("order.info", url_args={"order_id": order_id}))
425
426    def trades(self):
427        """
428        Retrieve the list of trades executed (all or ones under a particular order).
429
430        An order can be executed in tranches based on market conditions.
431        These trades are individually recorded under an order.
432        """
433        return self._format_response(self._get("trades"))
434
435    def order_trades(self, order_id):
436        """
437        Retrieve the list of trades executed for a particular order.
438
439        - `order_id` is the ID of the order to retrieve trade history.
440        """
441        return self._format_response(self._get("order.trades", url_args={"order_id": order_id}))
442
443    def positions(self):
444        """Retrieve the list of positions."""
445        return self._get("portfolio.positions")
446
447    def holdings(self):
448        """Retrieve the list of equity holdings."""
449        return self._get("portfolio.holdings")
450
451    def get_auction_instruments(self):
452        """ Retrieves list of available instruments for a auction session """
453        return self._get("portfolio.holdings.auction")
454
455    def convert_position(self,
456                         exchange,
457                         tradingsymbol,
458                         transaction_type,
459                         position_type,
460                         quantity,
461                         old_product,
462                         new_product):
463        """Modify an open position's product type."""
464        return self._put("portfolio.positions.convert", params={
465            "exchange": exchange,
466            "tradingsymbol": tradingsymbol,
467            "transaction_type": transaction_type,
468            "position_type": position_type,
469            "quantity": quantity,
470            "old_product": old_product,
471            "new_product": new_product
472        })
473
474    def mf_orders(self, order_id=None):
475        """Get all mutual fund orders or individual order info."""
476        if order_id:
477            return self._format_response(self._get("mf.order.info", url_args={"order_id": order_id}))
478        else:
479            return self._format_response(self._get("mf.orders"))
480
481    def place_mf_order(self,
482                       tradingsymbol,
483                       transaction_type,
484                       quantity=None,
485                       amount=None,
486                       tag=None):
487        """Place a mutual fund order."""
488        return self._post("mf.order.place", params={
489            "tradingsymbol": tradingsymbol,
490            "transaction_type": transaction_type,
491            "quantity": quantity,
492            "amount": amount,
493            "tag": tag
494        })
495
496    def cancel_mf_order(self, order_id):
497        """Cancel a mutual fund order."""
498        return self._delete("mf.order.cancel", url_args={"order_id": order_id})
499
500    def mf_sips(self, sip_id=None):
501        """Get list of all mutual fund SIP's or individual SIP info."""
502        if sip_id:
503            return self._format_response(self._get("mf.sip.info", url_args={"sip_id": sip_id}))
504        else:
505            return self._format_response(self._get("mf.sips"))
506
507    def place_mf_sip(self,
508                     tradingsymbol,
509                     amount,
510                     instalments,
511                     frequency,
512                     initial_amount=None,
513                     instalment_day=None,
514                     tag=None):
515        """Place a mutual fund SIP."""
516        return self._post("mf.sip.place", params={
517            "tradingsymbol": tradingsymbol,
518            "amount": amount,
519            "initial_amount": initial_amount,
520            "instalments": instalments,
521            "frequency": frequency,
522            "instalment_day": instalment_day,
523            "tag": tag
524        })
525
526    def modify_mf_sip(self,
527                      sip_id,
528                      amount=None,
529                      status=None,
530                      instalments=None,
531                      frequency=None,
532                      instalment_day=None):
533        """Modify a mutual fund SIP."""
534        return self._put("mf.sip.modify",
535                         url_args={"sip_id": sip_id},
536                         params={
537                             "amount": amount,
538                             "status": status,
539                             "instalments": instalments,
540                             "frequency": frequency,
541                             "instalment_day": instalment_day
542                         })
543
544    def cancel_mf_sip(self, sip_id):
545        """Cancel a mutual fund SIP."""
546        return self._delete("mf.sip.cancel", url_args={"sip_id": sip_id})
547
548    def mf_holdings(self):
549        """Get list of mutual fund holdings."""
550        return self._get("mf.holdings")
551
552    def mf_instruments(self):
553        """Get list of mutual fund instruments."""
554        return self._parse_mf_instruments(self._get("mf.instruments"))
555
556    def instruments(self, exchange=None):
557        """
558        Retrieve the list of market instruments available to trade.
559
560        Note that the results could be large, several hundred KBs in size,
561        with tens of thousands of entries in the list.
562
563        - `exchange` is specific exchange to fetch (Optional)
564        """
565        if exchange:
566            return self._parse_instruments(self._get("market.instruments", url_args={"exchange": exchange}))
567        else:
568            return self._parse_instruments(self._get("market.instruments.all"))
569
570    def quote(self, *instruments):
571        """
572        Retrieve quote for list of instruments.
573
574        - `instruments` is a list of instruments, Instrument are in the format of `exchange:tradingsymbol`. For example NSE:INFY
575        """
576        ins = list(instruments)
577
578        # If first element is a list then accept it as instruments list for legacy reason
579        if len(instruments) > 0 and type(instruments[0]) == list:
580            ins = instruments[0]
581
582        data = self._get("market.quote", params={"i": ins})
583        return {key: self._format_response(data[key]) for key in data}
584
585    def ohlc(self, *instruments):
586        """
587        Retrieve OHLC and market depth for list of instruments.
588
589        - `instruments` is a list of instruments, Instrument are in the format of `exchange:tradingsymbol`. For example NSE:INFY
590        """
591        ins = list(instruments)
592
593        # If first element is a list then accept it as instruments list for legacy reason
594        if len(instruments) > 0 and type(instruments[0]) == list:
595            ins = instruments[0]
596
597        return self._get("market.quote.ohlc", params={"i": ins})
598
599    def ltp(self, *instruments):
600        """
601        Retrieve last price for list of instruments.
602
603        - `instruments` is a list of instruments, Instrument are in the format of `exchange:tradingsymbol`. For example NSE:INFY
604        """
605        ins = list(instruments)
606
607        # If first element is a list then accept it as instruments list for legacy reason
608        if len(instruments) > 0 and type(instruments[0]) == list:
609            ins = instruments[0]
610
611        return self._get("market.quote.ltp", params={"i": ins})
612
613    def historical_data(self, instrument_token, from_date, to_date, interval, continuous=False, oi=False):
614        """
615        Retrieve historical data (candles) for an instrument.
616
617        Although the actual response JSON from the API does not have field
618        names such has 'open', 'high' etc., this function call structures
619        the data into an array of objects with field names. For example:
620
621        - `instrument_token` is the instrument identifier (retrieved from the instruments()) call.
622        - `from_date` is the From date (datetime object or string in format of yyyy-mm-dd HH:MM:SS.
623        - `to_date` is the To date (datetime object or string in format of yyyy-mm-dd HH:MM:SS).
624        - `interval` is the candle interval (minute, day, 5 minute etc.).
625        - `continuous` is a boolean flag to get continuous data for futures and options instruments.
626        - `oi` is a boolean flag to get open interest.
627        """
628        date_string_format = "%Y-%m-%d %H:%M:%S"
629        from_date_string = from_date.strftime(date_string_format) if type(from_date) == datetime.datetime else from_date
630        to_date_string = to_date.strftime(date_string_format) if type(to_date) == datetime.datetime else to_date
631
632        data = self._get("market.historical",
633                         url_args={"instrument_token": instrument_token, "interval": interval},
634                         params={
635                             "from": from_date_string,
636                             "to": to_date_string,
637                             "interval": interval,
638                             "continuous": 1 if continuous else 0,
639                             "oi": 1 if oi else 0
640                         })
641
642        return self._format_historical(data)
643
644    def _format_historical(self, data):
645        records = []
646        for d in data["candles"]:
647            record = {
648                "date": dateutil.parser.parse(d[0]),
649                "open": d[1],
650                "high": d[2],
651                "low": d[3],
652                "close": d[4],
653                "volume": d[5],
654            }
655            if len(d) == 7:
656                record["oi"] = d[6]
657            records.append(record)
658
659        return records
660
661    def trigger_range(self, transaction_type, *instruments):
662        """Retrieve the buy/sell trigger range for Cover Orders."""
663        ins = list(instruments)
664
665        # If first element is a list then accept it as instruments list for legacy reason
666        if len(instruments) > 0 and type(instruments[0]) == list:
667            ins = instruments[0]
668
669        return self._get("market.trigger_range",
670                         url_args={"transaction_type": transaction_type.lower()},
671                         params={"i": ins})
672
673    def get_gtts(self):
674        """Fetch list of gtt existing in an account"""
675        return self._get("gtt")
676
677    def get_gtt(self, trigger_id):
678        """Fetch details of a GTT"""
679        return self._get("gtt.info", url_args={"trigger_id": trigger_id})
680
681    def _get_gtt_payload(self, trigger_type, tradingsymbol, exchange, trigger_values, last_price, orders):
682        """Get GTT payload"""
683        if type(trigger_values) != list:
684            raise ex.InputException("invalid type for `trigger_values`")
685        if trigger_type == self.GTT_TYPE_SINGLE and len(trigger_values) != 1:
686            raise ex.InputException("invalid `trigger_values` for single leg order type")
687        elif trigger_type == self.GTT_TYPE_OCO and len(trigger_values) != 2:
688            raise ex.InputException("invalid `trigger_values` for OCO order type")
689
690        condition = {
691            "exchange": exchange,
692            "tradingsymbol": tradingsymbol,
693            "trigger_values": trigger_values,
694            "last_price": last_price,
695        }
696
697        gtt_orders = []
698        for o in orders:
699            # Assert required keys inside gtt order.
700            for req in ["transaction_type", "quantity", "order_type", "product", "price"]:
701                if req not in o:
702                    raise ex.InputException("`{req}` missing inside orders".format(req=req))
703            gtt_orders.append({
704                "exchange": exchange,
705                "tradingsymbol": tradingsymbol,
706                "transaction_type": o["transaction_type"],
707                "quantity": int(o["quantity"]),
708                "order_type": o["order_type"],
709                "product": o["product"],
710                "price": float(o["price"]),
711            })
712
713        return condition, gtt_orders
714
715    def place_gtt(
716        self, trigger_type, tradingsymbol, exchange, trigger_values, last_price, orders
717    ):
718        """
719        Place GTT order
720
721        - `trigger_type` The type of GTT order(single/two-leg).
722        - `tradingsymbol` Trading symbol of the instrument.
723        - `exchange` Name of the exchange.
724        - `trigger_values` Trigger values (json array).
725        - `last_price` Last price of the instrument at the time of order placement.
726        - `orders` JSON order array containing following fields
727            - `transaction_type` BUY or SELL
728            - `quantity` Quantity to transact
729            - `price` The min or max price to execute the order at (for LIMIT orders)
730        """
731        # Validations.
732        assert trigger_type in [self.GTT_TYPE_OCO, self.GTT_TYPE_SINGLE]
733        condition, gtt_orders = self._get_gtt_payload(trigger_type, tradingsymbol, exchange, trigger_values, last_price, orders)
734
735        return self._post("gtt.place", params={
736            "condition": json.dumps(condition),
737            "orders": json.dumps(gtt_orders),
738            "type": trigger_type})
739
740    def modify_gtt(
741        self, trigger_id, trigger_type, tradingsymbol, exchange, trigger_values, last_price, orders
742    ):
743        """
744        Modify GTT order
745
746        - `trigger_type` The type of GTT order(single/two-leg).
747        - `tradingsymbol` Trading symbol of the instrument.
748        - `exchange` Name of the exchange.
749        - `trigger_values` Trigger values (json array).
750        - `last_price` Last price of the instrument at the time of order placement.
751        - `orders` JSON order array containing following fields
752            - `transaction_type` BUY or SELL
753            - `quantity` Quantity to transact
754            - `price` The min or max price to execute the order at (for LIMIT orders)
755        """
756        condition, gtt_orders = self._get_gtt_payload(trigger_type, tradingsymbol, exchange, trigger_values, last_price, orders)
757
758        return self._put("gtt.modify",
759                         url_args={"trigger_id": trigger_id},
760                         params={
761                             "condition": json.dumps(condition),
762                             "orders": json.dumps(gtt_orders),
763                             "type": trigger_type})
764
765    def delete_gtt(self, trigger_id):
766        """Delete a GTT order."""
767        return self._delete("gtt.delete", url_args={"trigger_id": trigger_id})
768
769    def order_margins(self, params):
770        """
771        Calculate margins for requested order list considering the existing positions and open orders
772
773        - `params` is list of orders to retrive margins detail
774        """
775        return self._post("order.margins", params=params, is_json=True)
776
777    def _warn(self, message):
778        """ Add deprecation warning message """
779        warnings.simplefilter('always', DeprecationWarning)
780        warnings.warn(message, DeprecationWarning)
781
782    def _parse_instruments(self, data):
783        # decode to string for Python 3
784        d = data
785        # Decode unicode data
786        if not PY2 and type(d) == bytes:
787            d = data.decode("utf-8").strip()
788
789        records = []
790        reader = csv.DictReader(StringIO(d))
791
792        for row in reader:
793            row["instrument_token"] = int(row["instrument_token"])
794            row["last_price"] = float(row["last_price"])
795            row["strike"] = float(row["strike"])
796            row["tick_size"] = float(row["tick_size"])
797            row["lot_size"] = int(row["lot_size"])
798
799            # Parse date
800            if len(row["expiry"]) == 10:
801                row["expiry"] = dateutil.parser.parse(row["expiry"]).date()
802
803            records.append(row)
804
805        return records
806
807    def _parse_mf_instruments(self, data):
808        # decode to string for Python 3
809        d = data
810        if not PY2 and type(d) == bytes:
811            d = data.decode("utf-8").strip()
812
813        records = []
814        reader = csv.DictReader(StringIO(d))
815
816        for row in reader:
817            row["minimum_purchase_amount"] = float(row["minimum_purchase_amount"])
818            row["purchase_amount_multiplier"] = float(row["purchase_amount_multiplier"])
819            row["minimum_additional_purchase_amount"] = float(row["minimum_additional_purchase_amount"])
820            row["minimum_redemption_quantity"] = float(row["minimum_redemption_quantity"])
821            row["redemption_quantity_multiplier"] = float(row["redemption_quantity_multiplier"])
822            row["purchase_allowed"] = bool(int(row["purchase_allowed"]))
823            row["redemption_allowed"] = bool(int(row["redemption_allowed"]))
824            row["last_price"] = float(row["last_price"])
825
826            # Parse date
827            if len(row["last_price_date"]) == 10:
828                row["last_price_date"] = dateutil.parser.parse(row["last_price_date"]).date()
829
830            records.append(row)
831
832        return records
833
834    def _user_agent(self):
835        return (__title__ + "-python/").capitalize() + __version__
836
837    def _get(self, route, url_args=None, params=None, is_json=False):
838        """Alias for sending a GET request."""
839        return self._request(route, "GET", url_args=url_args, params=params, is_json=is_json)
840
841    def _post(self, route, url_args=None, params=None, is_json=False, query_params=None):
842        """Alias for sending a POST request."""
843        return self._request(route, "POST", url_args=url_args, params=params, is_json=is_json, query_params=query_params)
844
845    def _put(self, route, url_args=None, params=None, is_json=False, query_params=None):
846        """Alias for sending a PUT request."""
847        return self._request(route, "PUT", url_args=url_args, params=params, is_json=is_json, query_params=query_params)
848
849    def _delete(self, route, url_args=None, params=None, is_json=False):
850        """Alias for sending a DELETE request."""
851        return self._request(route, "DELETE", url_args=url_args, params=params, is_json=is_json)
852
853    def _request(self, route, method, url_args=None, params=None, is_json=False, query_params=None):
854        """Make an HTTP request."""
855        # Form a restful URL
856        if url_args:
857            uri = self._routes[route].format(**url_args)
858        else:
859            uri = self._routes[route]
860
861        url = urljoin(self.root, uri)
862
863        # Custom headers
864        headers = {
865            "X-Kite-Version": self.kite_header_version,
866            "User-Agent": self._user_agent()
867        }
868
869        if self.api_key and self.access_token:
870            # set authorization header
871            auth_header = self.api_key + ":" + self.access_token
872            headers["Authorization"] = "token {}".format(auth_header)
873
874        if self.debug:
875            log.debug("Request: {method} {url} {params} {headers}".format(method=method, url=url, params=params, headers=headers))
876
877        # prepare url query params
878        if method in ["GET", "DELETE"]:
879            query_params = params
880
881        try:
882            r = self.reqsession.request(method,
883                                        url,
884                                        json=params if (method in ["POST", "PUT"] and is_json) else None,
885                                        data=params if (method in ["POST", "PUT"] and not is_json) else None,
886                                        params=query_params,
887                                        headers=headers,
888                                        verify=not self.disable_ssl,
889                                        allow_redirects=True,
890                                        timeout=self.timeout,
891                                        proxies=self.proxies)
892        # Any requests lib related exceptions are raised here - https://requests.readthedocs.io/en/latest/api/#exceptions
893        except Exception as e:
894            raise e
895
896        if self.debug:
897            log.debug("Response: {code} {content}".format(code=r.status_code, content=r.content))
898
899        # Validate the content type.
900        if "json" in r.headers["content-type"]:
901            try:
902                data = r.json()
903            except ValueError:
904                raise ex.DataException("Couldn't parse the JSON response received from the server: {content}".format(
905                    content=r.content))
906
907            # api error
908            if data.get("status") == "error" or data.get("error_type"):
909                # Call session hook if its registered and TokenException is raised
910                if self.session_expiry_hook and r.status_code == 403 and data["error_type"] == "TokenException":
911                    self.session_expiry_hook()
912
913                # native Kite errors
914                exp = getattr(ex, data.get("error_type"), ex.GeneralException)
915                raise exp(data["message"], code=r.status_code)
916
917            return data["data"]
918        elif "csv" in r.headers["content-type"]:
919            return r.content
920        else:
921            raise ex.DataException("Unknown Content-Type ({content_type}) with response: ({content})".format(
922                content_type=r.headers["content-type"],
923                content=r.content))