{"id":25177906,"url":"https://github.com/axelgard/cira","last_synced_at":"2025-04-09T07:09:15.884Z","repository":{"id":47432098,"uuid":"286022721","full_name":"AxelGard/cira","owner":"AxelGard","description":"Cira algorithmic trading made easy. A Façade library for simpler interaction with alpaca SDK from Alpaca Markets.","archived":false,"fork":false,"pushed_at":"2025-02-08T07:14:16.000Z","size":8159,"stargazers_count":32,"open_issues_count":3,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T03:41:24.340Z","etag":null,"topics":["algo-trading","algotrading","alpaca","alpaca-api","alpaca-markets","alpaca-py","alpaca-trade-api","alpaca-trading-api","cira","crypto","finance","pypi","python","python-package","python3","quantitative-finance","stock-market","stocks","trading","trading-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AxelGard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-08T10:34:45.000Z","updated_at":"2025-01-01T12:01:28.000Z","dependencies_parsed_at":"2023-09-26T22:39:30.014Z","dependency_job_id":"88659fc4-ddd6-47eb-945b-eff8b8ab7d8d","html_url":"https://github.com/AxelGard/cira","commit_stats":{"total_commits":175,"total_committers":7,"mean_commits":25.0,"dds":"0.17142857142857137","last_synced_commit":"159ebec3e5aeb868f1628a9bcab3185cd2a05fbd"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxelGard%2Fcira","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxelGard%2Fcira/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxelGard%2Fcira/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxelGard%2Fcira/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AxelGard","download_url":"https://codeload.github.com/AxelGard/cira/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247994121,"owners_count":21030050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algo-trading","algotrading","alpaca","alpaca-api","alpaca-markets","alpaca-py","alpaca-trade-api","alpaca-trading-api","cira","crypto","finance","pypi","python","python-package","python3","quantitative-finance","stock-market","stocks","trading","trading-bot"],"created_at":"2025-02-09T14:49:55.061Z","updated_at":"2025-04-09T07:09:15.867Z","avatar_url":"https://github.com/AxelGard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cira\n\nCira algorithmic trading made easy. A [Façade library](https://refactoring.guru/design-patterns/facade) for simpler interaction with alpaca-trade-API from Alpaca Markets.\n\nCira is available on [pip](https://pypi.org/project/cira/). **Please give it a star if you like it!**\n\n\u003cimg src=\"https://raw.githubusercontent.com/AxelGard/cira/master/docs/img/cira.jpeg\" alt=\"drawing\" style=\"width:300px;\"/\u003e\n\n![GitHub stars](https://img.shields.io/github/stars/AxelGard/Cira?style=social)\n![GitHub forks](https://img.shields.io/github/forks/AxelGard/cira?style=social)\n[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/Axel_Gard)\n\n![GitHub](https://img.shields.io/github/license/AxelGard/cira?style=plastic)\n![PyPI](https://img.shields.io/pypi/v/cira)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cira)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/cira)\n\nThe name **cira** is a miss spelling of the word for a [baby alpaca cria](https://en.wikipedia.org/wiki/Cria) and because this is a simple and small lib I thought it would be a perfect fit.\n\n[Axel Gard](https://github.com/AxelGard) is main developer for cira.\n\n## Getting Started\n\nIf you are new to cira checkout the [tutorial](https://github.com/AxelGard/cira/wiki/Tutorial).\nOr checkout an [example](https://github.com/AxelGard/cira/blob/master/examples/linear.ipynb). \n\n### Installation\nYou can install it using [pip](https://pypi.org/project/cira/).\n```bash\npip install cira\n```\n\n### Usage\nSince the Alpaca trade API need a API key, you need to generate your own key at [alpaca markets website](https://app.alpaca.markets/signup). If you want to play around with it you can try paper trading (recommended for beginners). I recommend keep it in a **JSON file** which cira needs the **path** to.\nYou can also set the variables directly or use an environment variable, see the **[wiki](https://github.com/AxelGard/cira/wiki/Storing-the-Alpaca-API-key)** for diffrent the ways. However, it is **recommended** that you store it in a file just make sure not to upload that file on any public repositories. \n\nYou can set the Alpaca keys directly \n\n```python\nimport cira\n\ncira.auth.APCA_API_KEY_ID = \"my key\" \ncira.auth.APCA_API_SECRET_KEY = \"my secret key\"\n\nstock = cira.Stock(\"TSLA\")\nstock.buy(1) # buy 1 TSLA stock on alpaca \nstock.sell(1) # sell 1 TSLA stock on alpaca \n```\n\nFor interactons with alpaca you can:  \n```python\nportfolio = cira.Portfolio() # methods for your portfolio\nexchange = cira.Exchange() # methods for exchange\nstock = cira.Stock(\"TSLA\") # a class for one stock\ncrypto = cira.Cryptocurrency(\"BTC/USD\") # method for one cryptocurrency \n```\n\n### DEMO, no keys needed \n\nCrypto market data can be accessed [without any alpaca keys](https://alpaca.markets/sdks/python/market_data.html#api-keys).\nSo there for you can try cira out with out needing to get alpaca keys. \nTo put you model in production where you buy and sell you will need alpaca keys. \n\nNeeds `cira\u003e=3.2.2`.\n\n```python\nimport cira\nfrom datetime import datetime\nimport matplotlib.pyplot as plt\n\nassert not cira.auth.check_keys() # No keys are needed\n\nSYMBOL = \"BTC/USD\"\nast = cira.Cryptocurrency(SYMBOL)\n\nprint(f\"The current asking price for {SYMBOL} is {ast.price()}\")\n\n\n# alpaca only have BTC data from 2021 and forward \ndata = ast.historical_data_df(datetime(2021, 1, 1), datetime.now().date())\nprint(data.head())\n\n# All of strategies and backtesting works with out keys as well. \nstrat = cira.strategy.Randomness()\ncira.strategy.back_test_against_buy_and_hold(strat, data, data[\"open\"].to_frame(), 100_000).plot()\nplt.savefig('./result.png')\n```\n\nyou can find more examples on the **[examples repo](https://github.com/AxelGard/cira-examples)** and the **[wiki/tutorial](https://github.com/AxelGard/cira/wiki/Tutorial)** for even more information. \n\n### Cira Stratergies\n\nCira have also support for strategies.  \nAn **full example** of how to use the strategy is [example/linear](../../examples/linear.ipynb). \n\nWith strategies you can run a cira backtests.\n\n```python\nfrom cira.strategy import Strategy\nimport numpy as np\nimport pandas as pd\n\nclass MyStrat(Strategy):\n    def __init__(self) -\u003e None:\n        super().__init__(name=\"MyStrat\")\n\n    def iterate(self, feature_data: pd.DataFrame, prices: pd.DataFrame, portfolio: np.ndarray, cash:float) -\u003e np.ndarray:\n        # this mehod will be called for each row of data in the backtest \n        # the function should return the change of your portfolio. \n        # -1 means sell one stock, 0 means hold, 1 means buy one stock\n        return np.array([ portfolio_change_as_int_or_float ]) \n```\n\n#### Backtest\n\nIf your model is put into a strategy you can run a backtest on you own data.\nThis is a backtest using some of the included strategy in cira.\nYou can run a backtest aginst multiple strategies using the same data, this requires however that all features for all models are in the given data to the backtest.\nYou should of course add your own strategy, but as an example.\n\n```python\nimport cira\nfrom datetime import datetime\nimport matplotlib.pyplot as plt\n\nassert not cira.auth.check_keys() # back testing against crypto do not need keys \n\nSYMBOL = \"ETH/USD\"\nast = cira.Cryptocurrency(SYMBOL)\n\ndata = ast.historical_data_df(datetime(2021, 1, 1), datetime.now().date())\n\nstrats = [\n            cira.strategy.ByAndHold(),\n            cira.strategy.DollarCostAveraging(0.8),\n            cira.strategy.Randomness(-100, 100, seed=None, use_float=True),\n            # add your own strategy and compare your model against other models\n        ]\ncira.strategy.multi_strategy_backtest(strats, data, data[\"open\"].to_frame(), 100_000).plot()\nplt.savefig(\"./result.png\")\n```\n\nIf you want more full example of how to use the backtest checkout \n[multiassets](https://github.com/AxelGard/cira/blob/master/examples/multi_assets.ipynb) and \n[linear](https://github.com/AxelGard/cira/blob/master/examples/linear.ipynb).\n\n\n\n## Things to checkout\n\n* [News](https://github.com/AxelGard/cira/discussions/categories/news)\n* [Wiki](https://github.com/AxelGard/cira/wiki/)\n* [Tutorial](https://github.com/AxelGard/cira/wiki/Tutorial)\n* [Storing the Alpaca API key](https://github.com/AxelGard/cira/wiki/Storing-the-Alpaca-API-key)\n* [Examples of how to use cira](https://github.com/AxelGard/cira-examples)\n* [Discussions](https://github.com/AxelGard/cira/discussions)\n\n### [Wiki](https://github.com/AxelGard/cira/wiki) and docs\n\nTo see what more you can do check out the [wiki](https://github.com/AxelGard/cira/wiki).\n\n### Want the old version?\n\nFor backwards compatibility I made sure to fork cira in to [cira-classic](https://github.com/AxelGard/cira-classic) and cira-classic is also available on [pypi with pip](https://pypi.org/project/cira-classic/).\n\n**If you find bug plz let me know with a issue.** If you know how to solve the problem then you can of course make a pull request and I will take a look at it.\n\n### Have a question?\n\nIf you have a question about cira, want to share what you built with cira or want to talk to others using cira,\nyou can checkout the [discussions page](https://github.com/AxelGard/cira/discussions) or make issue if that is more fitting.\n\n### History of cira \n\nI was interested in using the Alpaca trade API for building a quantitative paper trader.\nThe project is available [here](https://github.com/AxelGard/paper-trader).\u003cbr\u003e\nHowever after working on this for alomst a year (off and on) I realized that I had alomst build a small library for using the Alpaca API.\nSo I thought that I would make this into a real library so that you can get started with quantitative paper trading as well.\n\n## Development\nIf you want to help develop cira you are more then welcome to do so.\nFeel free to make a pull request or issue.\nTo install cira with all the dev req.\n```bash\ngit clone git@github.com:AxelGard/cira.git\ncd cira/\ngit checkout develop\n```\nand know you need to  \n```bash\npython3 -m venv env\nsource env/bin/activate\npip install -e .\npip install -r requirements.txt\n```\nRun tests using pytest. Ensure that you are in the cira dir.\nBut you will need a new key. This key should not only be used for testing or if you don't mind if all of the assets in the portfolio being sold.   \n```bash\npytest -rP\n```\n\n### Coding style\nI'm trying to follow the [pep8](https://pep8.org/) standard notation.\nI try to make the library to be so intuitive as possible for easy of use.\n\nI enforce [black formater](https://github.com/psf/black) when you commit code, by [pre-commit githooks](https://git-scm.com/docs/githooks#_pre_commit) to keep it some what well formated.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/AxelGard/cira/blob/master/LICENSE.txt) file for details. \n\n\n## Acknowledgments\n\n* [Alpaca API](https://alpaca.markets/)\n* [paper-trader](https://github.com/AxelGard/paper-trader)\n* [cira-classic](https://github.com/AxelGard/cira-classic)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxelgard%2Fcira","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxelgard%2Fcira","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxelgard%2Fcira/lists"}