firstrade 0.0.1.1__py3-none-any.whl

firstrade/account.py

@@ -0,0 +1,220 @@
+import requests
+import pickle
+import re
+import os
+from time import sleep
+from bs4 import BeautifulSoup
+from firstrade import urls
+
+
+class FTSession:
+    """
+    Class creating a session for Firstrade.
+    """
+    def __init__(self, username, password, pin, persistent_session=True):
+        """
+        Initializes a new instance of the FTSession class.
+
+        Args:
+            username (str): Firstrade login username.
+            password (str): Firstrade login password.
+            pin (str): Firstrade login pin.
+            persistent_session (bool, optional): Whether the user wants to save the session cookies. Defaults to False.
+        """
+        self.username = username
+        self.password = password
+        self.pin = pin
+        self.persistent_session = persistent_session
+        self.session = requests.Session()
+        self.cookies = {}
+        self.login()
+
+    def login(self):
+        """
+        Method to validate and login to the Firstrade platform.
+        """
+        headers = urls.session_headers()
+        cookies = self.load_cookies()
+        cookies = requests.utils.cookiejar_from_dict(cookies)
+        self.session.cookies.update(cookies)
+        response = self.session.get(
+            url=urls.get_xml(), headers=urls.session_headers(), cookies=cookies
+        )
+        if response.status_code != 200:
+            raise Exception('Login failed. Check your credentials or internet connection.')
+        if "/cgi-bin/sessionfailed?reason=6" in response.text:
+            self.session.get(url=urls.login(), headers=headers)
+            data = {
+                'redirect': '',
+                'ft_locale': 'en-us',
+                'login.x': 'Log In',
+                'username': r'' + self.username,
+                'password': r'' + self.password,
+                'destination_page': 'home'
+            }
+
+            self.session.post(
+                url=urls.login(), headers=headers,
+                cookies=self.session.cookies, data=data
+            )
+            data = {
+                'destination_page': 'home',
+                'pin': self.pin,
+                'pin.x': '++OK++',
+                'sring': '0',
+                'pin': self.pin
+            }
+
+            self.session.post(
+                url=urls.pin(), headers=headers,
+                cookies=self.session.cookies, data=data
+            )
+            if self.persistent_session:
+                self.save_cookies()
+        self.cookies = self.session.cookies
+        if "/cgi-bin/sessionfailed?reason=6" in self.session.get(
+            url=urls.get_xml(), headers=urls.session_headers(), cookies=cookies
+        ).text:
+            raise Exception('Login failed. Check your credentials.')
+
+    def load_cookies(self):
+        """
+        Checks if session cookies were saved.
+
+        Returns:
+            Dict: Dictionary of cookies. Nom Nom
+        """
+        cookies = {}
+        for filename in os.listdir('.'):
+            if filename.endswith(f'{self.username}.pkl'):
+                with open(filename, 'rb') as f:
+                    cookies = pickle.load(f)
+        return cookies
+
+    def save_cookies(self):
+        """
+        Saves session cookies to a file.
+        """
+        with open(f'ft_cookies{self.username}.pkl', 'wb') as f:
+            pickle.dump(self.session.cookies.get_dict(), f)
+
+    def __getattr__(self, name):
+        """
+        Forwards unknown attribute access to session object.
+
+        Args:
+            name (str): The name of the attribute to be accessed.
+
+        Returns:
+            The value of the requested attribute from the session object.
+        """
+        return getattr(self.session, name)
+
+
+class FTAccountData:
+    """
+    Dataclass for storing account information.
+    """
+    def __init__(self, session):
+        """
+        Initializes a new instance of the FTAccountData class.
+
+        Args:
+            session (requests.Session): The session object used for making HTTP requests.
+        """
+        self.session = session
+        self.cookies = self.session.cookies
+        self.html_string = ''
+        self.all_accounts = []
+        self.account_numbers = []
+        self.account_statuses = []
+        self.account_balances = []
+        self.securities_held = {}
+        all_account_info = []
+        self.html_string = self.session.get(
+            url=urls.account_list(),
+            headers=urls.session_headers(),
+            cookies=self.cookies
+        ).text
+        regex_accounts = re.findall(
+            r"([0-9]+)-", self.html_string
+        )
+        
+        for match in regex_accounts:
+            self.account_numbers.append(match)
+        
+        for account in self.account_numbers:
+            data = {'accountId': account}
+            self.session.post(
+                url=urls.account_status(),
+                headers=urls.session_headers(),
+                cookies=self.session.cookies,
+                data=data
+            )
+            sleep(1)
+            data = {
+                    'page': 'bal',
+                    'account_id': account
+                }
+            account_soup = BeautifulSoup(self.session.post(
+                url=urls.get_xml(), 
+                headers=urls.session_headers(), 
+                cookies=self.session.cookies,
+                data=data,
+                ).text, 'xml')
+            balance = account_soup.find('total_account_value').text
+            self.account_balances.append(balance)
+            data = { 'req': 'get_status'}
+            account_status = self.session.post(
+                url=urls.status(),
+                headers=urls.session_headers(),
+                cookies=self.session.cookies,
+                data=data
+            ).json()
+            self.account_statuses.append(account_status['data'])
+    
+            all_account_info.append({account: 
+                {'Balance': balance, 'Status': 
+                    {'primary':account_status['data']['primary'], 'domestic':account_status['data']['domestic'], 
+                     'joint':account_status['data']['joint'], 'ira':account_status['data']['ira'],
+                     'hasMargin':account_status['data']['hasMargin'], 'opLevel':account_status['data']['opLevel'], 'p_country':account_status['data']['p_country'],
+                     'mrgnStatus':account_status['data']['mrgnStatus'], 'opStatus':account_status['data']['opStatus'], 'margin_id':account_status['data']['margin_id']
+                    }
+                 }})
+            
+        self.all_accounts = all_account_info
+
+    def get_positions(self, account):
+        """Gets currently held positions for a given account.
+
+        Args:
+            account (str): Account number of the account you want to get positions for.
+
+        Returns:
+            self.securities_held {dict}: Dict of held positions with the pos. ticker as the key.
+        """
+        data = {
+            'page': 'pos',
+            'accountId': str(account),
+        }
+        position_soup = BeautifulSoup(self.session.post(
+            url=urls.get_xml(),
+            headers=urls.session_headers(),
+            data=data,
+            cookies=self.cookies
+        ).text, 'xml')
+
+        tickers = position_soup.find_all('symbol')
+        quantity = position_soup.find_all('quantity')
+        price = position_soup.find_all('price')
+        change = position_soup.find_all('change')
+        change_percent = position_soup.find_all('changepercent')
+        vol = position_soup.find_all('vol')
+        for i, ticker in enumerate(tickers):
+            ticker = ticker.text
+            self.securities_held[ticker] = {
+                'quantity': quantity[i].text,
+                'price': price[i].text, 'change': change[i].text,
+                'change_percent': change_percent[i].text, 'vol': vol[i].text
+            }
+        return self.securities_held

firstrade/order.py

@@ -0,0 +1,141 @@
+from firstrade.account import FTSession
+from firstrade import urls
+from enum import Enum
+from bs4 import BeautifulSoup
+
+
+class PriceType(str, Enum):
+    """
+    This is an :class: 'enum.Enum' that contains the valid price types for an order.
+    """
+    LIMIT = '2'
+    MARKET = '1'
+    STOP = '3'
+    STOP_LIMIT = '4'
+    TRAILING_STOP_DOLLAR = '5'
+    TRAILING_STOP_PERCENT = '6'
+
+
+class Duration(str, Enum):
+    """
+    This is an :class:'~enum.Enum' that contains the valid durations for an order.
+    """
+    DAY = '0'
+    GT90 = '1'
+    PRE_MARKET = 'A'
+    AFTER_MARKET = 'P'
+    DAY_EXT = 'D'
+
+
+class OrderType(str, Enum):
+    """
+    This is an :class:'~enum.Enum' that contains the valid order types for an order.
+    """
+    BUY = 'B'
+    SELL = 'S'
+    SELL_SHORT = 'SS'
+    BUY_TO_COVER = 'BC'
+
+
+class Order:
+    """
+    This class contains information about an order. It also contains a method to place an order.
+    """
+    def __init__(self, ft_session: FTSession):
+        self.ft_session = ft_session
+        self.order_confirmation = {}
+
+    def place_order(
+        self, account, symbol, price_type: PriceType, order_type: OrderType,
+        quantity, duration: Duration, price=0.00, dry_run=True
+    ):
+
+        """
+        Builds and places an order.
+        :attr: 'order_confirmation` contains the order confirmation data after order placement.
+
+        Args:
+            account (str): Account number of the account to place the order in.
+            symbol (str): Ticker to place the order for.
+            order_type (PriceType): Price Type i.e. LIMIT, MARKET, STOP, etc.
+            quantity (float): The number of shares to buy.
+            duration (Duration): Duration of the order i.e. DAY, GT90, etc.
+            price (float, optional): The price to buy the shares at. Defaults to 0.00.
+            dry_run (bool, optional): Whether you want the order to be placed or not. 
+                                      Defaults to True.
+
+        Returns:
+            Order:order_confirmation: Dictionary containing the order confirmation data.
+        """
+
+        if dry_run:
+            previewOrders = '1'
+        else:
+            previewOrders = ''
+
+        if price_type == PriceType.MARKET:
+            price = ''
+        
+        data = {
+            'submiturl': '/cgi-bin/orderbar',
+            'orderbar_clordid': '',
+            'orderbar_accountid': '',
+            'stockorderpage': 'yes',
+            'submitOrders': '1',
+            'previewOrders': previewOrders,
+            'lotMethod': '1',
+            'accountType': '1',
+            'quoteprice': '',
+            'viewederror': '',
+            'stocksubmittedcompanyname1': '',
+            'accountId': account,
+            'transactionType': order_type,
+            'quantity': quantity,
+            'symbol': symbol,
+            'priceType': price_type,
+            'limitPrice': price,
+            'duration': duration,
+            'qualifier': '0',
+            'cond_symbol0_0': '',
+            'cond_type0_0': '2',
+            'cond_compare_type0_0': '2',
+            'cond_compare_value0_0': '',
+            'cond_and_or0': '1',
+            'cond_symbol0_1': '',
+            'cond_type0_1': '2',
+            'cond_compare_type0_1': '2',
+            'cond_compare_value0_1': ''
+        }
+
+        order_data = BeautifulSoup(self.ft_session.post(
+            url=urls.orderbar(),
+            headers=urls.session_headers(),
+            data=data
+        ).text, 'xml')
+        order_confirmation = {}
+        order_success = order_data.find('success').text.strip()
+        order_confirmation['success'] = order_success
+        action_data = order_data.find('actiondata').text.strip()
+        if order_success != "No":
+            # Extract the table data
+            table_start = action_data.find('<table')
+            table_end = action_data.find('</table>') + len('</table>')
+            table_data = action_data[table_start:table_end]
+            table_data = BeautifulSoup(table_data, 'xml')
+            titles = table_data.find_all('th')
+            data = table_data.find_all('td')
+            for i, title in enumerate(titles):
+                order_confirmation[f'{title.get_text()}'] = data[i].get_text()
+            if not dry_run:
+                start_index = action_data.find('Your order reference number is: ') + len('Your order reference number is: ')
+                end_index = action_data.find('</div>', start_index)
+                order_number = action_data[start_index:end_index]
+            else:
+                start_index = action_data.find('id="') + len('id="')
+                end_index = action_data.find('" style=', start_index)
+                order_number = action_data[start_index:end_index]
+            order_confirmation['orderid'] = order_number
+        else:
+            order_confirmation['actiondata'] = action_data
+        order_confirmation['errcode'] = order_data.find('errcode').text.strip()
+        self.order_confirmation = order_confirmation

firstrade/symbols.py

@@ -0,0 +1,54 @@
+from bs4 import BeautifulSoup
+from firstrade.account import FTSession
+from firstrade import urls
+
+
+class SymbolQuote:
+    """
+    Dataclass containing quote information for a symbol.
+
+    Attributes:
+        ft_session (FTSession): The session object used for making HTTP requests to Firstrade.
+        symbol (str): The symbol for which the quote information is retrieved.
+        exchange (str): The exchange where the symbol is traded.
+        bid (float): The bid price for the symbol.
+        ask (float): The ask price for the symbol.
+        last (float): The last traded price for the symbol.
+        change (float): The change in price for the symbol.
+        high (float): The highest price for the symbol during the trading day.
+        low (float): The lowest price for the symbol during the trading day.
+        volume (str): The volume of shares traded for the symbol.
+        company_name (str): The name of the company associated with the symbol.
+    """
+    def __init__(self, ft_session: FTSession, symbol: str):
+        """
+        Initializes a new instance of the SymbolQuote class.
+
+        Args:
+            ft_session (FTSession): The session object used for making HTTP requests to Firstrade.
+            symbol (str): The symbol for which the quote information is retrieved.
+        """
+        self.ft_session = ft_session
+        self.symbol = symbol
+        symbol_data = self.ft_session.get(
+            url=urls.quote(self.symbol),
+            headers=urls.session_headers()
+        )
+        soup = BeautifulSoup(symbol_data.text, 'xml')
+        quote = soup.find('quote')
+        self.symbol = quote.find('symbol').text
+        self.exchange = quote.find('exchange').text
+        self.bid = float(quote.find('bid').text)
+        self.ask = float(quote.find('ask').text)
+        self.last = float(quote.find('last').text)
+        self.change = float(quote.find('change').text)
+        if quote.find('high').text == 'N/A':
+            self.high = None
+        else:
+            self.high = float(quote.find('high').text)
+        if quote.find('low').text == 'N/A':
+            self.low = 'None'
+        else:
+            self.low = float(quote.find('low').text)
+        self.volume = quote.find('vol').text
+        self.company_name = quote.find('companyname').text

firstrade/urls.py

@@ -0,0 +1,45 @@
+
+
+def get_xml():
+    return 'https://invest.firstrade.com/cgi-bin/getxml'
+
+
+def login():
+    return 'https://invest.firstrade.com/cgi-bin/login'
+
+
+def pin():
+    return 'https://invest.firstrade.com/cgi-bin/enter_pin?destination_page=home'
+
+
+def account_list():
+    return 'https://invest.firstrade.com/cgi-bin/getaccountlist'
+
+
+def quote(symbol):
+    return f'https://invest.firstrade.com/cgi-bin/getxml?page=quo&quoteSymbol={symbol}'
+
+
+def orderbar():
+    return 'https://invest.firstrade.com/cgi-bin/orderbar'
+
+
+def account_status():
+    return 'https://invest.firstrade.com/cgi-bin/account_status'
+
+
+def status():
+    return "https://invest.firstrade.com/scripts/profile/margin_v2.php"
+
+
+def session_headers():
+    headers = {
+        'Accept': '*/*',
+        'Accept-Encoding': 'gzip, deflate, br',
+        'Accept-Language': 'en-US,en;q=0.9',
+        'Host': 'invest.firstrade.com',
+        'Referer': 'https://invest.firstrade.com/cgi-bin/main',
+        'Connection': 'keep-alive',
+        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36 Edg/116.0.1938.81'
+    }
+    return headers

firstrade-0.0.1.1.dist-info/LICENSE

@@ -0,0 +1,18 @@
+Copyright <2023> <MAXXRK>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy 
+of this software and associated documentation files (the “Software”), to deal 
+in the Software without restriction, including without limitation the rights 
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is 
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
+NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

firstrade-0.0.1.1.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.1
+Name: firstrade
+Version: 0.0.1.1
+Summary: An unofficial API for Firstrade
+Home-page: https://github.com/MaxxRK/firstrade-api
+Download-URL: https://github.com/MaxxRK/firstrade-api/archive/refs/tags/0.0.1.1.tar.gz
+Author: MaxxRK
+Author-email: maxxrk@pm.me
+License: MIT
+Keywords: FIRSTRADE,API
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: beautifulsoup4
+Requires-Dist: lxml
+
+# firstrade-api
+ A reverse-engineered python API to interact with the Firstrade Trading platform.
+
+ This is not an official api! This api's functionality may change at any time.
+
+ This api provides a means of buying and selling stocks through Firstrade. It uses the Session class from requests to get authorization cookies. The rest is done with reverse engineered requests to Firstrade's API. 
+
+ ---
+
+## Contribution
+I am new to coding and new to open-source. I would love any help and suggestions!
+
+## Setup
+Install using pypi:
+```
+pip install firstrade
+```
+
+## Quikstart
+The code below will: 
+- Login and print account info. 
+- Get a quote for 'INTC' and print out the information
+- Place a market order for 'INTC' on the first account in the `account_numbers` list
+- Print out the order confirmation
+
+```
+from firstrade import account
+from firstrade import symbols
+from firstrade import order
+
+# Create a session
+ft_ss = account.FTSession(username='', password='', pin='')
+
+# Get account data
+ft_accounts = account.FTAccountData(ft_ss)
+if len(ft_accounts.account_numbers) < 1:
+    raise Exception('No accounts found or an error occured exiting...')
+
+# Print ALL account data
+print(ft_accounts.all_accounts)
+
+# Print 1st account number.
+print(ft_accounts.account_numbers[0])
+
+# Print ALL accounts market values.
+print(ft_accounts.account_balances)
+
+# Get quote for INTC
+quote = symbols.SymbolQuote(ft_ss, 'INTC')
+print(f"Symbol: {quote.symbol}")
+print(f"Exchange: {quote.exchange}")
+print(f"Bid: {quote.bid}")
+print(f"Ask: {quote.ask}")
+print(f"Last: {quote.last}")
+print(f"Change: {quote.change}")
+print(f"High: {quote.high}")
+print(f"Low: {quote.low}")
+print(f"Volume: {quote.volume}")
+print(f"Company Name: {quote.company_name}")
+
+# Get positions and print them out for an account.
+positions = ft_accounts.get_positions(account=ft_accounts.account_numbers[1])
+for key in ft_accounts.securities_held:
+    print(f"Quantity {ft_accounts.securities_held[key]['quantity']} of security {key} held in account {ft_accounts.account_numbers[1]}")
+
+# Create an order object.   
+ft_order = order.Order(ft_ss)
+
+# Place order and print out order confirmation data.
+ft_order.place_order(
+    ft_accounts.account_numbers[0],
+    symbol='INTC',
+    price_type=order.PriceType.MARKET,
+    order_type=order.OrderType.BUY,
+    quantity=1,
+    duration=order.Duration.DAY,
+    dry_run=True
+)
+
+# Print Order data Dict
+print(ft_order.order_confirmation)
+
+# Check if order was successful
+if ft_order.order_confirmation['success'] == 'Yes':
+    print('Order placed successfully.')
+    # Print Order ID
+    print(f"Order ID: {ft_order.order_confirmation['orderid']}.")
+else:
+    print('Failed to place order.')
+    # Print errormessage
+    print(ft_order.order_confirmation['actiondata'])
+```
+This code is also in test.py
+
+---
+
+ ## Implemented Features
+ - [x] Login
+ - [x] Get Quotes
+ - [x] Get Account Data
+ - [x] Place Orders and Receive order confirmation
+ - [x] Get Currently Held Positions
+
+## TO DO
+- [ ] Check on placed order status.
+- [ ] Cancel placed orders
+- [ ] Options
+- [ ] Give me some Ideas!
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/O5O6PTOYG)  

firstrade-0.0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+firstrade/account.py,sha256=Vu7kQ4JxMo_Br-5EVVoj20pyWy51RBtyJETx5FGPYLc,7836
+firstrade/order.py,sha256=BmwPSb-kxBGBkZZ8ArbJmZOTx1z-Fq0y8-GbF2pDPAA,4992
+firstrade/symbols.py,sha256=4Uh8DjKhTSmQuR7KKp0OrdPVTBgr2e7k5EsmdNoVDPU,2297
+firstrade/urls.py,sha256=W6iNNypdjUXTjS9pNq74FxkjNJUnCeiXZ-C-mRpMyXY,1168
+firstrade-0.0.1.1.dist-info/LICENSE,sha256=wPEQjDqm5zMBmEcZp219Labmq_YIjhudpZiUzyVKaFA,1057
+firstrade-0.0.1.1.dist-info/METADATA,sha256=LtS9ifSKYZOMwyWItSnFhB7k1wY4bNOFX8nxMRDWKV8,4066
+firstrade-0.0.1.1.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
+firstrade-0.0.1.1.dist-info/top_level.txt,sha256=tdA8v-KDxU1u4VV6soiNWGBlni4ojv_t_j2wFn5nZcs,10
+firstrade-0.0.1.1.dist-info/RECORD,,

firstrade-0.0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.41.3)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

firstrade-0.0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+firstrade