firstrade 0.0.30__py3-none-any.whl → 0.0.33__py3-none-any.whl

firstrade/account.py

@@ -1,3 +1,4 @@
+import json
 import os
 import pickle
 
@@ -111,7 +112,10 @@ class FTSession:
             url=urls.login(),
             data=data,
         )
-        self.login_json = response.json()
+        try:
+            self.login_json = response.json()
+        except json.decoder.JSONDecodeError:
+            raise LoginResponseError("Invalid JSON is your account funded?")
         if (
             "mfa" not in self.login_json
             and "ftat" in self.login_json
@@ -326,16 +330,27 @@ class FTAccountData:
         response = self.session.get(urls.account_positions(account))
         return response.json()
 
-    def get_account_history(self, account):
+    def get_account_history(self, account, date_range="ytd", custom_range=None):
         """Gets account history for a given account.
 
         Args:
             account (str): Account number of the account you want to get history for.
+            range (str): The range of the history. Defaults to "ytd".
+                         Available options are
+                         ["today", "1w", "1m", "2m", "mtd", "ytd", "ly", "cust"].
+            custom_range (str): The custom range of the history.
+                                Defaults to None. If range is "cust",
+                                this parameter is required.
+                                Format: ["YYYY-MM-DD", "YYYY-MM-DD"].
 
         Returns:
             dict: Dict of the response from the API.
         """
-        response = self.session.get(urls.account_history(account))
+        if date_range == "cust" and custom_range is None:
+            raise ValueError("Custom range is required when date_range is 'cust'.")
+        response = self.session.get(
+            urls.account_history(account, date_range, custom_range)
+        )
         return response.json()
 
     def get_orders(self, account):

firstrade/exceptions.py

@@ -1,44 +1,55 @@
 class QuoteError(Exception):
     """Base class for exceptions in the Quote module."""
-    pass
+
 
 class QuoteRequestError(QuoteError):
     """Exception raised for errors in the HTTP request during a Quote."""
+
     def __init__(self, status_code, message="Error in HTTP request"):
         self.status_code = status_code
         self.message = f"{message}. HTTP status code: {status_code}"
         super().__init__(self.message)
 
+
 class QuoteResponseError(QuoteError):
     """Exception raised for errors in the API response."""
+
     def __init__(self, symbol, error_message):
         self.symbol = symbol
         self.message = f"Failed to get data for {symbol}. API returned the following error: {error_message}"
         super().__init__(self.message)
-        
+
+
 class LoginError(Exception):
     """Exception raised for errors in the login process."""
-    pass
+
 
 class LoginRequestError(LoginError):
     """Exception raised for errors in the HTTP request during login."""
+
     def __init__(self, status_code, message="Error in HTTP request during login"):
         self.status_code = status_code
         self.message = f"{message}. HTTP status code: {status_code}"
         super().__init__(self.message)
 
+
 class LoginResponseError(LoginError):
     """Exception raised for errors in the API response during login."""
+
     def __init__(self, error_message):
-        self.message = f"Failed to login. API returned the following error: {error_message}"
+        self.message = (
+            f"Failed to login. API returned the following error: {error_message}"
+        )
         super().__init__(self.message)
-        
+
+
 class AccountError(Exception):
     """Base class for exceptions in the Account module."""
-    pass
+
 
 class AccountResponseError(AccountError):
     """Exception raised for errors in the API response when getting account data."""
+
     def __init__(self, error_message):
         self.message = f"Failed to get account data. API returned the following error: {error_message}"
         super().__init__(self.message)

firstrade/order.py

@@ -149,7 +149,7 @@ class Order:
             raise ValueError("AON orders must be a limit order.")
         if order_instruction == OrderInstructions.AON and quantity <= 100:
             raise ValueError("AON orders must be greater than 100 shares.")
- 
+
         data = {
             "symbol": symbol,
             "transaction": order_type,
@@ -180,17 +180,17 @@ class Order:
         return response.json()
 
     def place_option_order(
-            self,
-            account: str,
-            option_symbol: str,
-            price_type: PriceType, 
-            order_type: OrderType,
-            contracts: int,
-            duration: Duration,
-            stop_price: float = None,
-            price: float = 0.00,
-            dry_run: bool = True,
-            order_instruction: OrderInstructions = "0",
+        self,
+        account: str,
+        option_symbol: str,
+        price_type: PriceType,
+        order_type: OrderType,
+        contracts: int,
+        duration: Duration,
+        stop_price: float = None,
+        price: float = 0.00,
+        dry_run: bool = True,
+        order_instruction: OrderInstructions = "0",
     ):
         """
         Builds and places an option order.
@@ -215,13 +215,12 @@ class Order:
         Returns:
             dict: A dictionary containing the order confirmation data.
         """
-        
+
         if order_instruction == OrderInstructions.AON and price_type != PriceType.LIMIT:
             raise ValueError("AON orders must be a limit order.")
         if order_instruction == OrderInstructions.AON and contracts <= 100:
             raise ValueError("AON orders must be greater than 100 shares.")
-            
-        
+
         data = {
             "duration": duration,
             "instructions": order_instruction,
@@ -233,7 +232,7 @@ class Order:
             "price_type": price_type,
         }
         if price_type in [PriceType.LIMIT, PriceType.STOP_LIMIT]:
-                data["limit_price"] = price
+            data["limit_price"] = price
         if price_type in [PriceType.STOP, PriceType.STOP_LIMIT]:
             data["stop_price"] = stop_price
 

firstrade/symbols.py

@@ -70,9 +70,9 @@ class SymbolQuote:
         self.change = response.json()["result"]["change"]
         self.high = response.json()["result"]["high"]
         self.low = response.json()["result"]["low"]
-        self.bid_mmid = response.json()["result"]["bid_mmid:"]
-        self.ask_mmid = response.json()["result"]["ask_mmid:"]
-        self.last_mmid = response.json()["result"]["last_mmid:"]
+        self.bid_mmid = response.json()["result"]["bid_mmid"]
+        self.ask_mmid = response.json()["result"]["ask_mmid"]
+        self.last_mmid = response.json()["result"]["last_mmid"]
         self.last_size = response.json()["result"]["last_size"]
         self.change_color = response.json()["result"]["change_color"]
         self.volume = response.json()["result"]["vol"]
@@ -88,7 +88,7 @@ class SymbolQuote:
         self.realtime = response.json()["result"]["realtime"]
         self.nls = response.json()["result"]["nls"]
         self.shares = response.json()["result"]["shares"]
-        
+
 
 class OptionQuote:
     """
@@ -112,7 +112,7 @@ class OptionQuote:
         self.ft_session = ft_session
         self.symbol = symbol
         self.option_dates = self.get_option_dates(symbol)
-        
+
     def get_option_dates(self, symbol: str):
         """
         Retrieves the expiration dates for options on a given symbol.
@@ -129,7 +129,7 @@ class OptionQuote:
         """
         response = self.ft_session.get(url=urls.option_dates(symbol))
         return response.json()
-    
+
     def get_option_quote(self, symbol: str, date: str):
         """
         Retrieves the quote for a given option symbol.
@@ -146,7 +146,7 @@ class OptionQuote:
         """
         response = self.ft_session.get(url=urls.option_quotes(symbol, date))
         return response.json()
-    
+
     def get_greek_options(self, symbol: str, exp_date: str):
         """
         Retrieves the greeks for options on a given symbol.

firstrade/urls.py

@@ -23,7 +23,9 @@ def account_balances(account):
 
 
 def account_positions(account):
-    return f"https://api3x.firstrade.com/private/positions?account={account}&per_page=200"
+    return (
+        f"https://api3x.firstrade.com/private/positions?account={account}&per_page=200"
+    )
 
 
 def quote(account, symbol):
@@ -38,8 +40,10 @@ def order_list(account):
     return f"https://api3x.firstrade.com/private/order_status?account={account}"
 
 
-def account_history(account):
-    return f"https://api3x.firstrade.com/private/account_history?range=ytd&page=1&account={account}&per_page=200"
+def account_history(account, date_range, custom_range):
+    if custom_range is None:
+        return f"https://api3x.firstrade.com/private/account_history?range={date_range}&page=1&account={account}&per_page=1000"
+    return f"https://api3x.firstrade.com/private/account_history?range={date_range}&range_arr[]={custom_range[0]}&range_arr[]={custom_range[1]}&page=1&account={account}&per_page=1000"
 
 
 def cancel_order():
@@ -67,7 +71,7 @@ def session_headers():
         "Accept-Encoding": "gzip",
         "Connection": "Keep-Alive",
         "Host": "api3x.firstrade.com",
-        "User-Agent": "okhttp/4.9.2",   
+        "User-Agent": "okhttp/4.9.2",
     }
     return headers
 

firstrade-0.0.33.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: firstrade
+Version: 0.0.33
+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/0033.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
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: beautifulsoup4
+Requires-Dist: lxml
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+# 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.
+
+In order to use Fractional shares you must accept the agreement on the website before using it in this API.
+
+---
+
+## Contribution
+
+Please feel free to contribute to this project. If you find any bugs, please open an issue.
+
+## Disclaimer
+I am not a financial advisor and not affiliated with Firstrade in any way. Use this tool at your own risk. I am not responsible for any losses or damages you may incur by using this project. This tool is provided as-is with no warranty.
+
+## Setup
+
+Install using pypi:
+
+```
+pip install firstrade
+```
+
+## Quikstart
+
+The code in `test.py` will:
+- Login and print account info.
+- Get a quote for 'INTC' and print out the information
+- Place a dry run market order for 'INTC' on the first account in the `account_numbers` list
+- Print out the order confirmation
+- Contains a cancel order example
+- Get an option Dates, Quotes, and Greeks
+- Place a dry run option order
+---
+
+## Implemented Features
+
+- [x] Login (With all 2FA methods now supported!) 
+- [x] Get Quotes
+- [x] Get Account Data
+- [x] Place Orders and Receive order confirmation
+- [x] Get Currently Held Positions
+- [x] Fractional Trading support (thanks to @jiak94)
+- [x] Check on placed order status. (thanks to @Cfomodz)
+- [x] Cancel placed orders
+- [x] Options (Orders, Quotes, Greeks)
+- [x] Order History
+
+## TO DO
+
+- [ ] Test options fully
+- [ ] Give me some Ideas!
+
+## Options
+
+### I am very new to options trading and have not fully tested this feature.
+
+Please:
+- USE THIS FEATURE LIKE IT IS A ALPHA/BETA
+- PUT IN A GITHUB ISSUE IF YOU FIND ANY PROBLEMS
+  
+## If you would like to support me, you can do so here:
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/maxxrk?style=social)](https://github.com/sponsors/maxxrk)

firstrade-0.0.33.dist-info/RECORD

@@ -0,0 +1,11 @@
+firstrade/__init__.py,sha256=fNiWYgSTjElY1MNv0Ug-sVLMTR2z_Ngri_FY7Pekdrw,95
+firstrade/account.py,sha256=wLPlQOzgaaBwb8tvYPcWdhfTtaUEtM54iPBl5dPpVHY,14129
+firstrade/exceptions.py,sha256=OrWB83rc33LSxrI7WxXo4o7FcIfmvPSC9bAY8K1pn7U,1886
+firstrade/order.py,sha256=_b1SnqagwBu7KUmvzSUcp8iMOC3I3k-QDjiDLhlVk7E,8710
+firstrade/symbols.py,sha256=RH36QLx5v3rKPpBidyJFwGJSDkF5u5f2ILTSZNAGXGQ,7903
+firstrade/urls.py,sha256=Iw10isyvoqKwiSl3TVuIbos5INZzIEwpln3HcZ7P5aw,2125
+firstrade-0.0.33.dist-info/licenses/LICENSE,sha256=wPEQjDqm5zMBmEcZp219Labmq_YIjhudpZiUzyVKaFA,1057
+firstrade-0.0.33.dist-info/METADATA,sha256=P5nB38P3U45tTO7kSbuPhuBYUb5DVfXEVcSPKxl55sQ,3367
+firstrade-0.0.33.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+firstrade-0.0.33.dist-info/top_level.txt,sha256=tdA8v-KDxU1u4VV6soiNWGBlni4ojv_t_j2wFn5nZcs,10
+firstrade-0.0.33.dist-info/RECORD,,

{firstrade-0.0.30.dist-info → firstrade-0.0.33.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (72.2.0)
+Generator: setuptools (78.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

firstrade-0.0.30.dist-info/METADATA

@@ -1,225 +0,0 @@
-Metadata-Version: 2.1
-Name: firstrade
-Version: 0.0.30
-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/0030.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.
-
-In order to use Fractional shares you must accept the agreement on the website before using it in this API.
-
----
-
-## Contribution
-
-I am new to coding and new to open-source. I would love any help and suggestions!
-
-## Disclaimer
-I am not a financial advisor and not affiliated with Firstrade in any way. Use this tool at your own risk. I am not responsible for any losses or damages you may incur by using this project. This tool is provided as-is with no warranty.
-
-## 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 dry run market order for 'INTC' on the first account in the `account_numbers` list
-- Print out the order confirmation
-- Contains a cancel order example
-- Get an option Dates, Quotes, and Greeks
-- Place a dry run option order
-
-```python
-from firstrade import account, order, symbols
-
-# Create a session
-ft_ss = account.FTSession(username="", password="", email = "", profile_path="")
-need_code = ft_ss.login()
-if need_code:
-    code = input("Please enter the pin sent to your email/phone: ")
-    ft_ss.login_two(code)
-
-# 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, ft_accounts.account_numbers[0], "INTC")
-print(f"Symbol: {quote.symbol}")
-print(f"Tick: {quote.tick}")
-print(f"Exchange: {quote.exchange}")
-print(f"Bid: {quote.bid}")
-print(f"Ask: {quote.ask}")
-print(f"Last: {quote.last}")
-print(f"Bid Size: {quote.bid_size}")
-print(f"Ask Size: {quote.ask_size}")
-print(f"Last Size: {quote.last_size}")
-print(f"Bid MMID: {quote.bid_mmid}")
-print(f"Ask MMID: {quote.ask_mmid}")
-print(f"Last MMID: {quote.last_mmid}")
-print(f"Change: {quote.change}")
-print(f"High: {quote.high}")
-print(f"Low: {quote.low}")
-print(f"Change Color: {quote.change_color}")
-print(f"Volume: {quote.volume}")
-print(f"Quote Time: {quote.quote_time}")
-print(f"Last Trade Time: {quote.last_trade_time}")
-print(f"Real Time: {quote.realtime}")
-print(f"Fractional: {quote.is_fractional}")
-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])
-print(positions)
-for item in positions["items"]:
-    print(
-        f"Quantity {item["quantity"]} of security {item["symbol"]} held in account {ft_accounts.account_numbers[1]}"
-    )
-
-# Get account history (past 200)
-history = ft_accounts.get_account_history(account=ft_accounts.account_numbers[0])
-for item in history["items"]:
-    print(f"Transaction: {item["symbol"]} on {item["report_date"]} for {item["amount"]}.")
-
-
-# Create an order object.
-ft_order = order.Order(ft_ss)
-
-# Place dry run order and print out order confirmation data.
-order_conf = ft_order.place_order(
-    ft_accounts.account_numbers[0],
-    symbol="INTC",
-    price_type=order.PriceType.LIMIT,
-    order_type=order.OrderType.BUY,
-    duration=order.Duration.DAY,
-    quantity=1,
-    dry_run=True,
-)
-
-print(order_conf)
-
-if "order_id" not in order_conf["result"]:
-    print("Dry run complete.")
-    print(order_conf["result"])
-else:
-    print("Order placed successfully.")
-    print(f"Order ID: {order_conf["result"]["order_id"]}.")
-    print(f"Order State: {order_conf["result"]["state"]}.")
-
-# Cancel placed order
-# cancel = ft_accounts.cancel_order(order_conf['result']["order_id"])
-# if cancel["result"]["result"] == "success":
-    # print("Order cancelled successfully.")
-# print(cancel)
-
-# Check orders
-recent_orders = ft_accounts.get_orders(ft_accounts.account_numbers[0])
-print(recent_orders)
-
-#Get option dates
-option_first = symbols.OptionQuote(ft_ss, "INTC")
-for item in option_first.option_dates["items"]:
-    print(f"Expiration Date: {item["exp_date"]} Days Left: {item["day_left"]} Expiration Type: {item["exp_type"]}")
-
-# Get option quote
-option_quote = option_first.get_option_quote("INTC", option_first.option_dates["items"][0]["exp_date"])
-print(option_quote)
-
-# Get option greeks
-option_greeks = option_first.get_greek_options("INTC", option_first.option_dates["items"][0]["exp_date"])
-print(option_greeks)
-
-print(f"Placing dry option order for {option_quote["items"][0]["opt_symbol"]} with a price of {option_quote["items"][0]["ask"]}.")
-print("Symbol readable ticker 'INTC'")
-
-# Place dry option order
-option_order = ft_order.place_option_order(
-    account=ft_accounts.account_numbers[0],
-    option_symbol=option_quote["items"][0]["opt_symbol"],
-    order_type=order.OrderType.BUY_OPTION,
-    price_type=order.PriceType.MARKET,
-    duration=order.Duration.DAY,
-    contracts=1,
-    dry_run=True,
-)
-
-print(option_order)
-
-# Delete cookies
-ft_ss.delete_cookies()
-```
-
-`You can also find this code in test.py`
-
----
-
-## Implemented Features
-
-- [x] Login (With all 2FA methods now supported!) 
-- [x] Get Quotes
-- [x] Get Account Data
-- [x] Place Orders and Receive order confirmation
-- [x] Get Currently Held Positions
-- [x] Fractional Trading support (thanks to @jiak94)
-- [x] Check on placed order status. (thanks to @Cfomodz)
-- [x] Cancel placed orders
-- [x] Options (Orders, Quotes, Greeks)
-- [x] Order History
-
-## TO DO
-
-- [ ] Test options fully
-- [ ] Give me some Ideas!
-
-## Options
-
-### I am very new to options trading and have not fully tested this feature.
-
-Please:
-- USE THIS FEATURE LIKE IT IS A ALPHA/BETA
-- PUT IN A GITHUB ISSUE IF YOU FIND ANY PROBLEMS
-  
-## If you would like to support me, you can do so here:
-[![GitHub Sponsors](https://img.shields.io/github/sponsors/maxxrk?style=social)](https://github.com/sponsors/maxxrk)

firstrade-0.0.30.dist-info/RECORD

@@ -1,11 +0,0 @@
-firstrade/__init__.py,sha256=fNiWYgSTjElY1MNv0Ug-sVLMTR2z_Ngri_FY7Pekdrw,95
-firstrade/account.py,sha256=U9U-LXmOS3pQK7WjQ3oXqlKvl3r-2kphBPvWGsD3q9Y,13287
-firstrade/exceptions.py,sha256=tL9hXGTZM1Ds0yWNCLSqD7hdcL_157CHLJT0e7AjxOg,1893
-firstrade/order.py,sha256=_IwKsJ58A8KxiiaFFNbGBE7sak4G23s4_uFaCSovx00,8789
-firstrade/symbols.py,sha256=9HKvg-rqX3GNCUKHtIOw81_MNkboamihmAaj6MpheW0,7930
-firstrade/urls.py,sha256=7jeIaRERP8yDbZrnw2QcWn2J0z2MYKSNFJhJvef8I2Q,1859
-firstrade-0.0.30.dist-info/LICENSE,sha256=wPEQjDqm5zMBmEcZp219Labmq_YIjhudpZiUzyVKaFA,1057
-firstrade-0.0.30.dist-info/METADATA,sha256=jNfpF431f4pEIsEBTc3dI8IUlIxhI4TZJcoXp0API8U,7186
-firstrade-0.0.30.dist-info/WHEEL,sha256=HiCZjzuy6Dw0hdX5R3LCFPDmFS4BWl8H-8W39XfmgX4,91
-firstrade-0.0.30.dist-info/top_level.txt,sha256=tdA8v-KDxU1u4VV6soiNWGBlni4ojv_t_j2wFn5nZcs,10
-firstrade-0.0.30.dist-info/RECORD,,