Tutorial

The basic setup

You can use the cira-group boilerplate if you want to get started fast.

Installation

Copy the repository using the github "Use this template" or clone the repository

When you have it downloaded you can start installing it. On macOS and Linux:

python3 -m venv env
source env/bin/activate
pip3 install -r requirements.txt

Key storge

Since the Alpaca trade API need an API key, you need to generate your own key at alpaca markets website. If you want to play around with it you can try paper trading (recommended for beginners). I recommend keeping it in a JSON file which cira needs the path to. You can also set the variables directly or use an environment variable, see the wiki for different ways. However, it is recommended that you store it in a file just make sure not to upload that file on any public repositories.
key.json

{
  "APCA-API-KEY-ID":"your_pub_key",
  "APCA-API-SECRET-KEY":"your_private_key"
}

Start using cira

then you can start using the lib

import cira
cira.alpaca.KEY_FILE = "../mypath/key.json"
stock = cira.Stock("TSLA")
stock.buy(1)
stock.sell(1)

How to use cira

Cira has three main classes that you interact with when building your trading bot.

portfolio = cira.Portfolio() # methods for your portfolio
exchange = cira.Exchange() # methods for exchange
stock = cira.Stock("TSLA") # a class for one stock

Protfolio

The portfolio class is for interaction with your own portfolio. So if you want to know what stocks you have in your portfolio you use the portfolio class.

import cira
cira.alpaca.KEY_FILE = "../mypath/key.json"
portfolio = cira.Portfolio()
print(portfolio.owned_stocks)

Exchange

The exchange class is for interactions with exchanges NASDAQ, NYSE, ARCA, BATS. When interacting with the class you do not need to specify which of the exchange you want to interact with, that is automated. So you can check if the exchange is open or what stocks are available when you use the exchange class. The exchange uses the Stock class for each stock in the exchange.

import cira
cira.alpaca.KEY_FILE = "../mypath/key.json"
exchange = cira.Exchange()
if exchange.is_open():
    print(exchange.get_all_stocks())

Stock

The stock class is for interaction with a single stock, like TSLA. So if you want to the price, buy, sell, or other types of interactions with a single stock. Indifference from the exchange or portfolio class, you don't need to initialize the class yourself, instead, you can ask the exchange. If you want you can of course, but mostly you will access a stock through the exchange.

import cira
cira.alpaca.KEY_FILE = "../mypath/key.json"
exchange = cira.Exchange()
while exchange.is_open():
    for stk in exchange.get_all_stocks():
        stk.buy(1)

or direct interaction with a stock by symbol

import cira
cira.alpaca.KEY_FILE = "../mypath/key.json"
exchange = cira.Exchange()
stk = cira.Stock("TSLA")
while exchange.is_open():
   stk.buy(1)

missing functionality in cira?

If there is some missing functionality in cira but that functionality exists in the alpaca lib. You can directly interact with the alpaca lib through the cira lib by accessing the alpc_client in both exchange or any of the asset classes.

import cira
cira.alpaca.KEY_FILE = "../mypath/key.json"
cira.alpaca_utils().get_trading_client().get_clock().is_open

logging

Cira allows for logging your trades, this might be useful for tracking your trades or for tax purposes. If you want to enable logging you need to give a path where to save the file, this file and is only local. The trades are saved into a CSV file.

import cira
cira.config.IS_LOGGING = True
cira.config.LOG_FILE = "./log.csv"