Alpaca-Finance-Python

  

An unofficial Python3.9+ package that wraps Binance Smart Chain positions on the Alpaca Finance platform to simplify interaction with their smart contracts in your Python projects.

Supported Position Types

Automated Vaults

NOTE: Existing users please update to the latest version of the package before using, core functionality has changed in version 1+.

Table of Contents

1. Installation
2. Usage
3. Uninstallation

---

Installation

This package is set up to be installed using the pip package manager.

1. Install the package using pip (you must use the git+url as this project is private and not listed on PyPi):

   pip install --upgrade alpaca-finance

2. After install, the package will be available to you in your local Python environment as alpaca_finance

When updates are made to the package, the version will automatically be incremented so that in order to get the newest version on your end, you can simply use the same installation command and your pip will detect and update to the newest version.

---

Usage

How to use the package

Automated Vaults:

1. Import the package into your Python script:

   from alpaca_finance.automated_vault import AutomatedVaultPosition

2. Creating an AutomatedVaultPosition instance requires the following:

   • Your position key (string)

     • This key should match your position key on Alpaca Finance's webapp
     • 

   • Your public wallet key (string)

   • (Optional) Your private wallet key (string)

     • Your private key is required to sign transactions, but can be left as None if you are only going to be using the informational methods.

   Once you've gathered all of these variables, you can create the position instance like this example below:

   position = AutomatedVaultPosition(position_key="n3x-BNBBUSD-PCS1", owner_wallet_address="0x...", owner_private_key="123abc456efg789hij...")

3. How to approve tokens:

   • Tokens that have never been approved on the Alpaca web interface will need to be approved programmatically
   • The current options for token approval are as follows:

     1. Using the AutomatedVaultPosition.auto_token_approval attribute:

        # Set to False by default
        # Tokens are only approved if the allowance is insufficent for the transaction
        position.auto_token_approval = True

     2. Using the AutomatedVaultPosition.do_approve_token method:

        See the approve_token.ipynb example file

4. Use your position instance to interact with Alpaca Finance:

   • For reference, see the BEP20Token class documentation
   • Please view the usage examples under examples/automated_vault

   """ Informational Methods (Private Key not Required) """
   
   # Get the asset token or stable token for the vault (BEP20Token object)
   position.asset_token, position.stable_token
   
   
   # Get the current yields for the vault:
   position.yields()
   
   
   # Get the current vault TVL:
   position.tvl()
   
   
   # Get the current vault capacity:
   position.capacity()
   
   
   # Get the position's cost basis (entry price in USD):
   position.cost_basis()
   
   
   # Get the current position value (in USD):
   position.current_value()
   
   
   # Get the position profit/loss (PnL in USD):
   position.pnl()
   
   
   # Get the amount of shares held and the USD value of all shares held:
   position.shares()
   
   
   # get the full vault summary (See the documentation alpaca_fiance/position.py for more details):
   position.get_vault_summary()
   
   
   """ Transactional Methods (Private Key Required) """
   
   
   # Approve a token for deposit to the vault (only required once if never approved):
   position.do_approve_token(<token_address> or <BEP20Token object>)
   # Approve the vault token for withdraw if using the "Convert All" strategy (only required once if never approved):
   position.do_approve_token(position.bep20_vault_token, _spender=position.gateway.address)
   
   
   # Invest the given amount of stable and asset token into the vault:
   position.do_invest(<stable_token_amt>, <asset_token_amt>)
   
   
   # Withdraw the given amount of shares from the vault:
   # Available strategies: "Minimize Trading" and "Convert All" (as shown on the webapp)
   
   # Using the "Minimize Trading" strategy (default, so not necessary to specify strategy):
   position.do_withdraw(<shares_amt>)
   # Using the "Convert All" strategy (must specify, and provide the percentage of stable token to receive):
   position.do_withdraw(<shares_amt>, <pct_stable_token>, strategy="Convert All")  
   
   
   # Close a position (remove all shares):
   
   # (default) Using the "Minimize Trading" strategy:
   position.do_close()
   # Optionally specify the "Convert All" strategy:
   position.do_close(<pct_stable_token>, strategy="Convert All")

---

Uninstallation:

Uninstall the package like any other Python package using the pip uninstall command:

pip uninstall alpaca-finance

Contributions:

Coming soon...