Skip to content

FYERS Mapping (from sample_codes/fyers_samples)

Note: A newer operator-friendly mapping exists under docs/fyers/. See docs/fyers/mapping.md, docs/fyers/rest-payloads.md, and docs/fyers/ws-payloads.md for structured references.

This file summarizes the FYERS SDK sample usage as a reference mapping for REST/WS operations.

It also includes sample WebSocket payloads that were previously documented separately.

Auth & Session (fyers_apiv3.fyersModel.SessionModel)

  • generate_authcode() -> opens login flow to obtain auth_code
  • set_token(auth_code) + generate_token() -> access token

Symbol Master (CSV sources)

These links can change; store them in config so they can be updated without code changes. - NSE Currency Derivatives: https://public.fyers.in/sym_details/NSE_CD.csv - NSE Equity Derivatives: https://public.fyers.in/sym_details/NSE_FO.csv - NSE Commodity: https://public.fyers.in/sym_details/NSE_COM.csv - NSE Capital Market: https://public.fyers.in/sym_details/NSE_CM.csv - BSE Capital Market: https://public.fyers.in/sym_details/BSE_CM.csv - BSE Equity Derivatives: https://public.fyers.in/sym_details/BSE_FO.csv - MCX Commodity: https://public.fyers.in/sym_details/MCX_COM.csv

CSV Headers (FYERS symbol master): - Fytoken, Symbol Details, Exchange Instrument type, Minimum lot size - Tick size, ISIN, Trading Session, Last update date, Expiry date - Symbol ticker, Exchange, Segment, Scrip code, Underlying symbol - Underlying scrip code, Strike price, Option type, Underlying FyToken - Reserved column (string), Reserved column (int), Reserved column (float) Config location: - config/symbol_master_sources.yaml

REST (fyers_apiv3.fyersModel.FyersModel)

  • get_profile()
  • funds()
  • market_status()
  • quotes(data={"symbols": "SYM1,SYM2"})
  • depth(data={"symbol": "NSE:SBIN-EQ", "ohlcv_flag": "1"})
  • history(data={"symbol": ..., "resolution": ..., "date_format": "0", "range_from": ..., "range_to": ..., "cont_flag": "1"})
  • orderbook() / orderbook(data={"id": order_id})
  • tradebook()
  • positions()
  • holdings()
  • place_order(data={"symbol": ..., "qty": ..., "type": ..., "side": ..., "productType": ..., "limitPrice": ..., "stopPrice": ..., "validity": ..., "disclosedQty": ..., "offlineOrder": False})
  • modify_order(data={"id": order_id, "type": ..., "limitPrice": ..., "qty": ...})
  • cancel_order(data={"id": order_id})
  • place_basket_orders(data=[{...}, {...}])
  • modify_basket_orders(data=[{...}, {...}])
  • cancel_basket_orders(data=[{"id": ...}, {"id": ...}])
  • exit_positions(data={}) or exit_positions(data={"id": "SYM-BO"})
  • convert_position(data={"symbol": ..., "positionSide": ..., "convertQty": ..., "convertFrom": ..., "convertTo": ...})

Notes: - FyersModel constructor: client_id, token, is_async, log_path - Rate limits (per user/IP, REST): 10 req/sec, 200 req/min, 100,000 req/day. Exceeding per-minute more than 3 times in a day can block API access for the day. Keep a safety buffer and backoff on 429/503. - ProductType policy (repo): allow list only (CNC, INTRADAY). CO/BO/MARGIN/MTF are disabled so strategies manage exits explicitly.

History resolution values (FYERS-native): - Daily: D or 1D - Seconds: 5S, 10S, 15S, 30S, 45S - Minutes: 1, 2, 3, 5, 10, 15, 20, 30, 60, 120, 240

Repo note: - This repo canonicalizes equivalent aliases (e.g., 1m -> 1, 5s -> 5S, 1D -> D) so REST calls and cache keys stay consistent. - Values confirmed from FYERS docs on 2026-01-17; update this list if FYERS changes supported resolutions.

Market Data WebSocket (FyersWebsocket.data_ws.FyersDataSocket)

  • connect()
  • subscribe(symbols=[...], data_type="SymbolUpdate" | "DepthUpdate")
  • unsubscribe(symbols=[...], data_type=...)
  • keep_running()
  • params: access_token "appid:accesstoken", litemode, write_to_file, reconnect
  • callbacks: on_connect, on_close, on_error, on_message Reconnect notes:
  • Separate connection from order WS.
  • Auto-reconnect can be enabled (reconnect=True) with configurable retry count.
  • Do not assume identical heartbeat or sequencing semantics vs the Order WebSocket. Subscription guidance:
  • Batch subscribe calls at 100 symbols per message.
  • Enforce the overall 5,000-symbol limit by unsubscribing unused symbols.

Sample L1 fields (SymbolUpdate): - symbol, type, ltp, vol_traded_today, last_traded_time, exch_feed_time - bid_size, ask_size, bid_price, ask_price, last_traded_qty - tot_buy_qty, tot_sell_qty, avg_trade_price - low_price, high_price, open_price, prev_close_price, ch, chp Sample index fields (SymbolUpdate, type "if"): - symbol, ltp, exch_feed_time, high_price, low_price, open_price - prev_close_price, ch, chp

Example payload (SymbolUpdate, fields may vary): 

{
  "symbol": "NSE:SBIN-EQ",
  "type": "symbolUpdate",
  "ltp": 731.4,
  "vol_traded_today": 23491195,
  "last_traded_time": 1704273001000,
  "exch_feed_time": 1704273001000,
  "bid_size": 300,
  "ask_size": 37,
  "bid_price": 731.3,
  "ask_price": 731.4,
  "last_traded_qty": 2,
  "tot_buy_qty": 28301400,
  "tot_sell_qty": 11084300,
  "avg_trade_price": 730.59,
  "low_price": 724.9,
  "high_price": 734.4,
  "open_price": 731.4,
  "prev_close_price": 730.45,
  "ch": 0.95,
  "chp": 0.13
}

Order WebSocket (FyersWebsocket.order_ws.FyersOrderSocket)

  • connect()
  • subscribe(data_type="OnOrders" | "OnTrades" | "OnPositions" | "OnGeneral" | comma-separated)
  • keep_running()
  • callbacks: on_orders, on_trades, on_positions, on_general, on_connect, on_close, on_error
  • This socket is for notifications only; all order create/modify/cancel actions are REST-only. Ping:
  • Send "ping" every ~10 seconds; expect "pong" to confirm liveness. Reconnect/resubscribe:
  • If disconnected, obtain a new WS access token, reconnect, then resubscribe.
  • Recommended resilience: after reconnect/resubscribe, fetch REST orderbook/tradebook/positions and treat REST as source of truth. Notes:
  • Some guidance mentions auto-reconnect up to 50 retries; a forum note mentions 5 attempts. Treat as configurable and confirm in practice.

Order id aliasing (CO/BO / parent-child orders): - FYERS payloads can contain multiple identifiers (e.g., request_id/requestId, id, orderNumber, and potentially parent/child ids for CO/BO). - This repo currently aliases the common request_id → final id case, but does NOT fully normalize CO/BO parent/child id relationships. - To harden this, we need real FYERS REST+WS payload samples for CO/BO covering: place_order response, order WS updates, and orderbook snapshot shapes. - Until those samples are available, treat CO/BO aliasing behavior as "best-effort" and validate with live captures before relying on it in production. Sample Order fields (orders): - clientId, id, exchOrdId, qty, filledQty, limitPrice, type, fyToken - exchange, segment, symbol, instrument, offlineOrder, orderDateTime - orderValidity, productType, side, status, source, ex_sym, description - orderNumStatus Sample Trade fields (trades): - tradeNumber, orderNumber, tradedQty, tradePrice, tradeValue, productType - clientId, exchangeOrderNo, orderType, side, symbol, orderDateTime - fyToken, exchange, segment Sample Position fields (positions): - symbol, id, buyAvg, buyQty, buyVal, sellAvg, sellQty, sellVal - netAvg, netQty, side, qty, productType, realized_profit, rbiRefRate - fyToken, exchange, segment, dayBuyQty, daySellQty, cfBuyQty, cfSellQty - qtyMulti_com

Example payloads (fields may vary):

Orders: 

{
  "id": "22010200015939",
  "qty": 1,
  "filledQty": 1,
  "limitPrice": 1,
  "type": 2,
  "fyToken": "101000000699",
  "orderDateTime": "2018-09-06 12:18:33",
  "productType": "INTRADAY",
  "side": 1,
  "status": 2,
  "symbol": "NSE:SBIN-EQ"
}

Trades: 

{
  "tradeNumber": "278785",
  "orderNumber": "22010200015939",
  "tradedQty": 1,
  "tradePrice": 5,
  "productType": "INTRADAY",
  "exchange": "NSE",
  "segment": "EQUITY",
  "symbol": "NSE:SBIN-EQ",
  "orderDateTime": "2018-09-06 12:18:33"
}

Positions: 

{
  "symbol": "NSE:SBIN-EQ",
  "qty": 1,
  "side": 1,
  "productType": "INTRADAY",
  "buyAvg": 5,
  "sellAvg": 0,
  "buyQty": 1,
  "sellQty": 0,
  "netAvg": 5,
  "netQty": 1
}
Notes: - tradeNumber is unique per execution within an account and stable across WS + REST tradebook. - id (FYERS order id) is unique within an account; namespace by account_id for storage. - remainingQuantity is optional in order updates; derive from qty and filledQty when missing.

TBT WebSocket (FyersWebsocket.tbt_ws.FyersTbtSocket)

  • connect()
  • subscribe(symbol_tickers=[...], channelNo="1", mode=SubscriptionModes.DEPTH)
  • switchChannel(resume_channels=[...], pause_channels=[...])
  • keep_running()
  • callbacks: on_depth_update, on_error_message, on_open, on_close, on_error