{"id":25650760,"url":"https://github.com/sgerodes/python-three-commas","last_synced_at":"2025-04-15T19:39:04.323Z","repository":{"id":37996450,"uuid":"448109010","full_name":"sgerodes/python-three-commas","owner":"sgerodes","description":null,"archived":false,"fork":false,"pushed_at":"2022-09-07T17:26:50.000Z","size":282,"stargazers_count":8,"open_issues_count":1,"forks_count":16,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-13T01:37:34.091Z","etag":null,"topics":["3commas","3commas-api","bitcoin","bot","bots","btc","crypto","eth","ethereum","python","python3","three-commas","trading"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sgerodes.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}},"created_at":"2022-01-14T21:13:26.000Z","updated_at":"2025-03-13T17:30:05.000Z","dependencies_parsed_at":"2022-09-12T03:11:52.458Z","dependency_job_id":null,"html_url":"https://github.com/sgerodes/python-three-commas","commit_stats":null,"previous_names":["badass-blockchain/python-three-commas"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgerodes%2Fpython-three-commas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgerodes%2Fpython-three-commas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgerodes%2Fpython-three-commas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sgerodes%2Fpython-three-commas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sgerodes","download_url":"https://codeload.github.com/sgerodes/python-three-commas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654027,"owners_count":21140236,"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":["3commas","3commas-api","bitcoin","bot","bots","btc","crypto","eth","ethereum","python","python3","three-commas","trading"],"created_at":"2025-02-23T15:18:34.571Z","updated_at":"2025-04-15T19:39:04.284Z","avatar_url":"https://github.com/sgerodes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Title\n\nThis library provides tools that help develop code that access the \n[3commas api](https://github.com/3commas-io/3commas-official-api-docs) very fast and easy. \nThe library is built on top of the py3cw library.\nMain features are prebuilt functions for the api, models for easier access of the returned data, \nautomatic attribute parsing of the returned data, built in error parsing. \n\nWIP: this library is still in construction. Some endpoints implementations are missing. Feel free to create a PR in github \nif you desire a particular endpoint implementation https://github.com/badass-blockchain/python-three-commas\n\n## Installation\n\n    pip install three-commas\n\n## Usage\n\nThe package is built mirroring the names of the api paths. For example:\n\n    from three_commas import api\n\n    api.ver1.bots # bots endpoint\n    api.ver1.accounts # account endpoint\n    api.ver1.deals # deals endpoint\n    api.ver1.users # users endpoint\n    api.v2.smart_trades # v2 smart_trades endpoint\n\nThe endpoints are mirrored from the paths too.\n    \n    # GET /ver1/bots/pairs_black_list\n    error, black_list_pairs = api.ver1.bots.get_pairs_black_list()\n\n    # GET /v2/smart_trades/{id}\n    error, smart_trades_list = api.v2.smart_trades.get_by_id(id=\u003cyour_smart_trade_id\u003e)\n\n\nYou can get all bots with: \n\n    error, bots_list = api.ver1.bots.get()\n\nOr a single bot with:\n\n    error, bot = api.ver1.bots.get_show_by_id(bot_id=\u003cyour_bot_id\u003e)\n\nOr a smart trade\n\n    error, smart_trade = api.v2.smart_trades.get_by_id(id=9993000)\n\nThe endpoints return a dict object with added functionality. You can use the object like a normal dictionary \n(exactly how you receive from py3cw), or use the added functions. \nFor example if you want to get the bot max_active_deals you can do both:\n\n    error, bot = api.ver1.bots.get_show_by_id(bot_id=9999999)\n    if not error:\n        max_active_deals = bot['max_active_deals']\n        max_active_deals = bot.max_active_deals\n\n### Websocket Streams\n\nYou can easily connect to the websockets \nYou can use annotations.\n\n    import three_commas\n    from three_commas.model import DealEntity, SmartTradeV2Entity\n\n    @three_commas.streams.smart_trades\n    def handle_smart_trades(smart_trade: SmartTradeV2Entity):\n        # Do here something with the smart trade\n        # Every new smart trade is passed to this function\n        print(smart_trade)\n\n    @three_commas.streams.deals\n    def handle_deals(deal: DealEntity):\n        # do your awesome stuff with the deal\n        print(deal)  #  {'id': 1311811868, 'type': 'Deal', 'bot_id': 6313165, 'max_safety_orders': 6, 'deal_has_error': False ....\n        print(deal.account_id)  #  99648312\n        print(deal.created_at)  #  string object '2022-02-18T05:26:06.803Z'\n        print(deal.parsed(True).created_at)  #  datetime.datetime object \n\n\nIn order to use the websocket streams you need to set the api key and secret in your environment.\n[Later in the document you can find how to set up the environment variables](#Set the api key and secret)\n\nOr you can pass the keys to the decorator:\n\n    @three_commas.streams.deals(api_key='\u003cyour_api_key\u003e', secret='\u003cyour_secret\u003e')\n    def handle_deals(deal):\n        ...\n\n\nFor debugging you can turn on debug level\n\n    import logging\n\n    logging.getLogger('three_commas.streams').setLevel(level=logging.DEBUG)\n\nYou will see a lot of websocket messages including pings:\n\n    \u003e DEBUG:three_commas.streams.streams: {\"type\": \"welcome\"}\n    \u003e DEBUG:three_commas.streams.streams: {\"type\": \"ping\", \"message\": 1645286932}\n    \u003e DEBUG:three_commas.streams.streams: {\"type\": \"ping\", \"message\": 1645286935}\n    \u003e DEBUG:three_commas.streams.streams: {\"type\": \"ping\", \"message\": 1645286938}\n\nYou can also set up the level to info for less verbose loging\n    logging.getLogger('three_commas.streams').setLevel(level=logging.INFO)\n\n\n### Parsing\nOne of the features of this library is the automatic parsing of the returned data. \nSome numeric data fetched from the api is returned as string. For example in the bot object:\n\n    ...\n    \"base_order_volume\": \"0.003\",\n    \"safety_order_volume\": \"0.003\",\n    \"safety_order_step_percentage\": \"1.0\",\n    ...\n\nNow you do not need to bother checking the type of the field and parsing it into the desired type.\nThis library auto parses these fields:\n\n    error, bot = api.ver1.bots.get_show(9999999)\n    # base_order_volume is a float\n    base_order_volume = bot.get_base_order_volume() \n\n    \nParsing (except datetime fields) is done by default. \nIf you do not want the field to be parsed, and you want the original string to be returned use parsed=False\n\n    error, bot = api.ver1.bots.get_show(9999999)\n    # base_order_volume is a str\n    base_order_volume = bot.parsed(False).base_order_volume \n\n\nSome fields like \"created_at\" are timestamps. You can parse these fields to a python datetime object. \nTimestamp fields are NOT parsed by default, only on demand:\n\n    error, account = api.ver1.accounts.get_by_id(8888888)\n\n    # the original string returned by the api\n    created_at_str = account.created_at\n\n    # parsed into a datetime.datetime object\n    created_at_datetime = account.parsed(True).created_at\n\n\n### Api keys\n\nIn order to use the api you need to set the api key and secret. This could be done globally or per request.\nTo set it globally you need to set the environment variables THREE_COMMAS_API_KEY and THREE_COMMAS_API_SECRET.\nTo do it per request just pass them into the function:\n\n    error, account = api.ver1.accounts.get_by_id(8888888, api_key='my_key', api_secret='my_secret')\n\nRequest keys have priority. If both global and request keys are set, then the request keys will be used.\n\n### Forced mode\n\nYou can set the forced mode globally or also per request.\nTo set it globally set the environment variable THREE_COMMAS_FORCED_MODE to either paper or real.\nTo use the forced mode per request pass it as an argument:\n\n    error, paper_deals = api.ver1.deals.get(forced_mode='paper')\n    error, real_deals = api.ver1.deals.get(forced_mode='real')\n\n\n### Enums\n\nSome enum fields have functionality. \n\n    error, accounts_list = api_v1.accounts.get_accounts()\n    if not error:\n        for account in accounts_list:\n            if account.get_market_code().is_binance():\n                # do stuff with the binance account.\n    else:\n        # deal with error here\n\nYou can check what enums are available in the three_commas.model.generated_enums package\n\n### Set the api key and secret\n\nAlways make sure your api keys are stored securely and are not pushed into any public repositories\n\n#### dotenv file and dotenv loader (preferred, more secure)\n\nYou can set key and secret as an environment variables. The preferred more secure way is to use a .env file:\n\ncreate a file called \".env\" with the following content:\n\n    THREE_COMMAS_API_KEY=\u003cyour_api_key\u003e\n    THREE_COMMAS_API_SECRET=\u003cyour_api_secret\u003e\n\nUse a .env loader as python-dotenv. Install it on your machine with pip: \"pip install python-dotenv\".\nIf your project is a git project make sure you gitignore the .env file.\nThen in your code\n\n    from dotenv import load_dotenv\n    load_dotenv()\n\nNow your variables are loaded. Enjoy using the library.\n\n#### setting the environment variable with the os module (less secure)\n\nYou can also set the api key and secret directly in the code. This method is less secure and not recommended.\n    \n    import os\n\n    os.environ[\"THREE_COMMAS_API_KEY\"] = \u003cyour_api_key\u003e\n    os.environ[\"THREE_COMMAS_API_SECRET\"] = \u003cyour_api_secret\u003e\n\n\n\n### Examples\n#### Posting a new smart trade\n    smart_trade = {\n        'account_id': 99999999,\n        'pair': 'USDT_FUN',\n        'position': {\n            'type': 'buy',\n            'order_type': 'market',\n            'units': {\n                'value': \"30526.0\",\n            },\n            \"total\": {\n                \"value\": \"600.61907506\"\n            }\n        },\n        'take_profit': {\n            'enabled': False,\n        },\n        'stop_loss': {\n            'enabled': False,\n        }\n\n    }\n\n    error, smart_trade_response = api.v2.smart_trades.post(smart_trade)\n\n#### Retrieving a smart trade\n\n    error, smart_trade = api.v2.smart_trades.get_by_id(13819196)\n    if not error:\n        # Do your awesome stuff with the smart trade\n        print(smart_trade.profit)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgerodes%2Fpython-three-commas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsgerodes%2Fpython-three-commas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsgerodes%2Fpython-three-commas/lists"}