Samco Broker Integration

Relevant source files

The following files were used as context for generating this wiki page:

• lib/stolgo/samco.py
• lib/stolgo/request.py
• lib/stolgo/helper.py
• lib/stolgo/common.py
• README.md

The Samco Broker Integration is a core data-fetching module within the stolgo library that allows users to retrieve financial market data specifically from Samco Securities (StockNote). It serves as a specialized connector for obtaining historical and intraday candle data, as well as option chain information, which can then be used for price action analysis and backtesting.

This integration facilitates the transition from raw broker API responses to structured pandas.DataFrame objects. It handles authentication via session tokens and manages the differences between equity stock data and index data (e.g., NIFTY 50) automatically based on the provided symbol.

Sources: lib/stolgo/samco.py:1-20, README.md:1-15

Architecture and Components

The integration is structured into three primary layers: the URL builder, the main interface class, and a robust request handling utility.

Component Overview

Component	Class/Module	Description
URL Management	SamcoUrl	Manages endpoint strings, headers, and builds formatted URLs for API requests.
Primary Interface	Samco	The user-facing class that handles login, session persistence, and data retrieval methods.
Request Utility	RequestUrl	A wrapper around the requests library providing retries, timeouts, and session management.
Helper Functions	stolgo.helper	Provides date range calculations and Indian index validation used by the integration.

Sources: lib/stolgo/samco.py:17-158, lib/stolgo/request.py:65-95, lib/stolgo/helper.py:1-85

Class Hierarchy

The following diagram illustrates the relationship between the Samco integration classes and the underlying request infrastructure.

Authentication and Session Management

Accessing Samco's data requires an active session token. Upon instantiation, the Samco class performs an automated login using the StockNote API.

1. Login Request: Sends userId, password, and yob (Year of Birth) to the LOGIN_URL.
2. Token Extraction: Retrieves the sessionToken from the JSON response.
3. Session Setup: Updates the x-session-token header in SamcoUrl for all subsequent data requests.

Sources: lib/stolgo/samco.py:68-84

Data Retrieval Logic

The integration provides a unified get_data method that abstracts the complexity of choosing between historical and intraday endpoints.

Request Flow

The system determines the appropriate API endpoint based on the requested interval. If the interval is "1D" (one day) or greater, it uses the historical API; otherwise, it utilizes the intraday API.

Index vs. Stock Handling

Samco uses different endpoints for individual stocks versus market indices (like NIFTY BANK). The module uses is_ind_index to check the symbol against a list of known Indian indices defined in stolgo.common.

• Stocks: Uses candleData endpoints.
• Indices: Uses indexCandleData endpoints.

Sources: lib/stolgo/samco.py:46-65, lib/stolgo/common.py:1-13

API Reference and Configuration

Constructor Parameters

The Samco class initialization requires the following credentials:

Parameter	Type	Description
user_id	str	Samco client ID.
password	str	Samco login password.
yob	int	Year of Birth (as secondary authentication).
timeout	int	Connection timeout in seconds (Default: 5).
max_retries	int	Maximum retry attempts for failed requests (Default: 2).

Sources: lib/stolgo/samco.py:11-15, 68-71

get_data Method

Fetches candle data for a specific symbol.

def get_data(self, symbol, start=None, end=None, periods=None, interval="1D", dayfirst=False):

• Returns: pandas.DataFrame containing OHLC (Open, High, Low, Close) and Volume data.
• Logic: If the requested timeframe does not match the native API resolution (e.g., 5-minute candles from a 1-minute API), the module uses get_data_resample to aggregate the data.

Sources: lib/stolgo/samco.py:116-155, lib/stolgo/helper.py:87-90

Error Handling

The integration relies on RequestUrl to handle network-level issues. It uses a TimeoutHTTPAdapter to enforce timeouts and a retry strategy that triggers on specific HTTP status codes: 429 (Rate Limit), 500, 502, 503, and 504.

Sources: lib/stolgo/request.py:13-25, 69-78

The Samco class itself wraps data fetching in try-except blocks, raising descriptive exceptions when data is unavailable or the API returns an error.

Sources: lib/stolgo/samco.py:99, 114, 158

Summary

The Samco Broker Integration provides a high-level abstraction for interacting with Samco Securities' StockNote API. By automating session management, symbol classification (Index vs. Stock), and data resampling, it allows developers to focus on strategy development using structured market data. It integrates seamlessly with the rest of the stolgo library's analytic tools like CandleStick patterns or Breakout detection.

Sources: lib/stolgo/samco.py:1-160, README.md:10-35