{"id":34113607,"url":"https://github.com/gunthardeniro/gunbot-sdk-python","last_synced_at":"2026-04-02T01:02:04.082Z","repository":{"id":301373258,"uuid":"1005211362","full_name":"GuntharDeNiro/gunbot-sdk-python","owner":"GuntharDeNiro","description":"Python client for Gunbot, a self hosted trading bot for crypto / ETF / stocks.","archived":false,"fork":false,"pushed_at":"2025-06-26T13:58:43.000Z","size":525,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-17T03:16:21.997Z","etag":null,"topics":["crypto","etf","gunbot","python","sdk","stocks","trading-bot"],"latest_commit_sha":null,"homepage":"https://www.gunbot.com","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/GuntharDeNiro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2025-06-19T21:27:14.000Z","updated_at":"2025-10-15T14:07:55.000Z","dependencies_parsed_at":"2025-06-26T14:52:48.021Z","dependency_job_id":"c97a3af7-6453-4aa0-9386-c74093108cc7","html_url":"https://github.com/GuntharDeNiro/gunbot-sdk-python","commit_stats":null,"previous_names":["gunthardeniro/gunbot-sdk-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GuntharDeNiro/gunbot-sdk-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-sdk-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-sdk-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-sdk-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-sdk-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GuntharDeNiro","download_url":"https://codeload.github.com/GuntharDeNiro/gunbot-sdk-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-sdk-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["crypto","etf","gunbot","python","sdk","stocks","trading-bot"],"created_at":"2025-12-14T19:16:29.217Z","updated_at":"2026-04-02T01:02:04.020Z","avatar_url":"https://github.com/GuntharDeNiro.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e \u003cimg src=\"/assets/logo.svg\" width=\"96\" alt=\"Gunbot SDK logo\"\u003e\u003c/p\u003e\n\n\n\n# Gunbot SDK for **Python**\n\n**Python client for the Gunbot REST API for automated crypto‑/ETF‑/stock trading**\n\n[![PyPI](https://img.shields.io/pypi/v/gunbot-sdk-python.svg)](https://pypi.org/project/gunbot-sdk-python)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n\u003e Programmatically control **Gunbot** – the self‑hosted automated trading bot – from Python scripts, notebooks, CI jobs or serverless functions.\n\n---\n\n## Key Features\n\n* **100 % OpenAPI 3.0 generated** – every endpoint stays in sync with Gunbot Core\n* **Typed models \u0026 services** – PEP 561 compliant type hints for better IDE experience\n* Single source that works in **CPython ≥ 3.9** and **PyPy**\n* **Zero dynamic dependencies** beyond the auto‑generated `urllib3` stack\n* MIT‑licensed – free for commercial and open‑source use\n\n---\n\n## Table of Contents\n\n1. [Installation](#installation)\n2. [Quick Start](#quick-start)\n3. [Configuration](#configuration)\n4. [Supported Exchanges](#supported-exchanges)\n5. [API Coverage](#api-coverage)\n6. [Type Hints](#type-hints)\n7. [Authentication](#authentication)\n8. [Examples](#examples)\n9. [Troubleshooting](#troubleshooting)\n10. [Contributing](#contributing)\n11. [License](#license)\n\n---\n\n## Installation\n\n```bash\n# pip\nto install: pip install gunbot-sdk-python\n# poetry\npoetry add gunbot-sdk-python\n# pipenv\npipenv install gunbot-sdk-python\n```\n\nThe distribution installs an **import package** named `gunbot_sdk`.\n\n---\n\n## Quick Start\n\n```python\nfrom datetime import datetime, timedelta\nfrom gunbot_sdk import ApiClient, GunbotApi\n\n# 1 – configure the shared ApiClient\napi = ApiClient(\n    base_path=\"http://localhost:3000/api/v1\",   # ← REST base\n    bearer_token=\"\u003cJWT‑TOKEN\u003e\"                   # ← your bearer token\n)\n\n# 2 – create a service wrapper\ngunbot = GunbotApi(api)\n\n# 3 – call an endpoint\nprint(\"orders:\", gunbot.orders(\"binance/USDT-BTC\"))\n```\n\n\u003e Replace `base_path` and `bearer_token` with values from your own Gunbot deployment.\n\nDocumentation for every method is generated under `docs/`, and available on github pages: [documentation](https://gunthardeniro.github.io/gunbot-python-js/).\n\n\u003e You need an appropriate [Gunbot plan](https://www.gunbot.com) to use this SDK effectively.\n\n---\n\n## Configuration\n\n| Option                                 | Default                        | Description                                           |\n| -------------------------------------- | ------------------------------ | ----------------------------------------------------- |\n| `base_path` (parameter of `ApiClient`) | `http://localhost:3000/api/v1` | Gunbot REST base path                                 |\n| `bearer_token`                         | –                              | JWT from GUI localStorage or `/auth/login` |\n| `timeout` (`ApiClient` kwarg)          | `60_000` ms                    | Request timeout                                       |\n| `user_agent` (`ApiClient` kwarg)       | `gunbot-sdk-python/\u003cversion\u003e`  | Custom UA header                                      |\n\n---\n\n## Supported Exchanges\n\n\u003e Gunbot ships with native connectors for **25 + exchanges**.\n\n| Exchange                     | Spot |       Futures / Perps      | DeFi (on‑chain) | Extra notes         |\n| ---------------------------- | :--: | :------------------------: | :-------------: | ------------------- |\n| **Binance**                  |  ✔️  |     ✔️ (USD‑M \u0026 COIN‑M)    |                 | Largest liquidity   |\n| **Binance US**               |  ✔️  |                            |                 | US‑regulated arm    |\n| **Bitget**                   |  ✔️  |    ✔️ (USDT \u0026 UM perps)    |                 |                     |\n| **Bybit**                    |  ✔️  |  ✔️ (USDT \u0026 inverse perps) |                 |                     |\n| **OKX**                      |  ✔️  | ✔️ (Perps \u0026 dated futures) |                 |                     |\n| **Kraken**                   |  ✔️  |   ✔️ (via Kraken Futures)  |                 |                     |\n| **KuCoin**                   |  ✔️  |                            |                 |                     |\n| **Gate.io**                  |  ✔️  |                            |                 |                     |\n| **MEXC**                     |  ✔️  |                            |                 |                     |\n| **BingX**                    |  ✔️  |                            |                 |                     |\n| **Crypto.com**               |  ✔️  |                            |                 |                     |\n| **Huobi Global**             |  ✔️  |                            |                 |                     |\n| **Bitfinex**                 |  ✔️  |                            |                 |                     |\n| **HitBTC**                   |  ✔️  |                            |                 |                     |\n| **Coinbase Advanced Trade**  |  ✔️  |                            |                 | Former Coinbase Pro |\n| **CEX.io**                   |  ✔️  |                            |                 |                     |\n| **Poloniex**                 |  ✔️  |                            |                 |                     |\n| **Alpaca** (stocks \u0026 crypto) |  ✔️  |                            |                 |                     |\n| **dYdX (v3/v4)**             |      |             ✔️             |        ✔️       | Perpetual DEX       |\n| **HyperLiquid**              |  ✔️  |             ✔️             |        ✔️       | DeFi perps          |\n| **PancakeSwap**              |      |             ✔️             |        ✔️       | BSC DEX             |\n| **Bitmex / Bitmex Testnet**  |      |             ✔️             |                 |                     |\n\n---\n\n## API Coverage\n\nThis SDK targets **Gunbot REST v1** (`/api/v1`), built from the official OpenAPI spec.\n\n| Tag / Section | Status |\n| ------------- | ------ |\n| Auth          | ✅      |\n| Market Data   | ✅      |\n| Orders        | ✅      |\n| Strategy      | ✅      |\n| Wallet        | ✅      |\n| Exchange Mgmt | ✅      |\n\n---\n\n## Type Hints\n\nThe wheel ships PEP 561 metadata so editors such as **VS Code**, **PyCharm** or **Neovim (pylsp)** show inline completions and docstrings.\n\n---\n\n## Authentication\n\n* **Bearer Token** – easiest: copy from Gunbot GUI `localStorage.jwtToken`.\n* **Password Encryption** – To fetch a token programmatically, follow the [Gunbot docs](https://www.gunbot.com/support/docs/rest-api/api-auth/#encryption-helpers).\n* Always use **HTTPS** when connecting over public networks.\n\n---\n\n## Examples\n\nThe code sets up the SDK client, creates a `GunbotApi` instance, and calls most of the available endpoints, so you can run it once to verify connectivity and see the expected argument patterns and raw responses. Use it as a reference checklist when integrating the SDK.\n\n``` python\n#!/usr/bin/env python3\n\"\"\"\nrun_examples.py – complete parity demo for the Gunbot Python SDK\nRequires:  pip install gunbot-sdk   (your renamed package)\n\nHOW IT WORKS ------------------------------------------------------\n1.  ApiClient sets REST base + Bearer token in one call.\n2.  Every endpoint uses snake_case.\n3.  POST/PUT endpoints take the JSON payload as 1st arg **body=...**.\n4.  Path/query-only endpoints map exactly to their URL params.\n-------------------------------------------------------------------\n\"\"\"\n\nfrom datetime import datetime, timedelta\nfrom gunbot_sdk import ApiClient, GunbotApi\n\n\ndef ts(*, days: int = 0, hours: int = 0) -\u003e int:\n    \"\"\"Return a UTC Unix timestamp in **milliseconds** with offset.\"\"\"\n    return int((datetime.utcnow() + timedelta(days=days, hours=hours)).timestamp() * 1000)\n\n\ndef main() -\u003e None:\n    # ───────────────── 1. CLIENT CONFIG ─────────────────\n    api_client = ApiClient(\n        base_path=\"http://localhost:3000/api/v1\",\n        bearer_token=\"\u003cYOUR-JWT-HERE\u003e\",\n    )\n\n    # ───────────────── 2. SERVICE WRAPPER ───────────────\n    gunbot = GunbotApi(api_client)\n\n    # ───────────────── 3. EXAMPLES ──────────────────────\n    # ---------- SYSTEM / AUTH ----------\n    print(\"auth_status:\", gunbot.auth_status())\n    print(\"time:\", gunbot.time())\n    print(\"system_start:\", gunbot.system_start())\n    print(\"system_stop:\", gunbot.system_stop())\n\n    # ---------- CONFIGURATION ----------\n    print(\"config_full:\", gunbot.config_full())\n\n    print(\"config_update:\", gunbot.config_update(body={\n        \"data\": {}      # full Gunbot config object\n    }))\n\n    print(\"config_pair_add:\", gunbot.config_pair_add(body={\n        \"pair\": \"USDT-BTC\",\n        \"exchange\": \"binance\",\n        \"settings\": {\n            \"strategy\": \"stepgrid\",\n            \"enabled\": True,\n            \"override\": {\n                \"BUY_METHOD\": \"stepgrid\",\n                \"SELL_METHOD\": \"stepgrid\",\n                \"GAIN\": \"2\",\n            },\n        },\n    }))\n\n    print(\"config_pair_remove:\", gunbot.config_pair_remove(body={\n        \"pair\": \"USDT-BTC\",\n        \"exchange\": \"binance\",\n    }))\n\n    print(\"config_strategy_add:\", gunbot.config_strategy_add(body={\n        \"name\": \"MY-STRATEGY\",\n        \"settings\": {\"SOME_PARAM\": True, \"MORE_PARAMS\": 2},\n    }))\n\n    print(\"config_strategy_remove:\", gunbot.config_strategy_remove(body={\n        \"name\": \"MY-STRATEGY\",\n    }))\n\n    # ---------- MARKET DATA ----------\n    print(\"assets_total:\", gunbot.assets_total(body={\n        \"exchange\": \"binance\",\n        \"base\": \"USDT\",\n        \"start\": ts(days=-1),\n        \"end\": ts(),\n    }))\n\n    print(\"chart_data:\", gunbot.chart_data(body={\n        \"exchange\": \"binance\",\n        \"pair\": \"USDT-BTC\",\n        \"interval\": \"1h\",\n        \"start\": ts(days=-3),\n        \"end\": ts(),\n    }))\n\n    print(\"chart_marks:\", gunbot.chart_marks(\n        \"binance\", \"USDT-BTC\", \"1h\", ts(days=-1), ts()\n    ))\n\n    print(\"market_candles:\", gunbot.market_candles(\"binance/USDT-BTC\"))\n    print(\"market_orderbook:\", gunbot.market_orderbook(\"binance/USDT-BTC\"))\n\n    # ---------- CORE MEMORY ----------\n    print(\"coremem:\", gunbot.coremem())\n\n    print(\"coremem_request:\", gunbot.coremem_request(body={\n        \"exchange\": \"binance\",\n        \"pair\": \"USDT-BTC\",\n        \"elements\": [],\n    }))\n\n    print(\"coremem_single:\", gunbot.coremem_single(body={\n        \"exchange\": \"binance\",\n        \"pair\": \"USDT-BTC\",\n    }))\n\n    # ---------- ORDERS ----------\n    print(\"orders:\", gunbot.orders(\"binance/USDT-BTC\"))\n    print(\"orders_page:\", gunbot.orders_page(\"binance/USDT-BTC\", 0, 50))\n    print(\"orders_page_multi:\", gunbot.orders_page_multi(\n        [\"binance/USDT-BTC\", \"binance/USDT-BTC\"], 0, 100\n    ))\n    print(\"orders_day:\", gunbot.orders_day(\"Europe/Berlin\", [\"binance/USDT-BTC\"]))\n\n    # ---------- BALANCES \u0026 PAIRS ----------\n    print(\"balances:\", gunbot.balances())\n    print(\"pairs:\", gunbot.pairs(\"binance\"))\n    print(\"pairs_detailed:\", gunbot.pairs_detailed(\"binance\"))\n\n    # ---------- PNL ----------\n    print(\"pnl_daily:\", gunbot.pnl_daily(\"binance/USDT-BTC\", ts(days=-1), ts()))\n    print(\"pnl_daily_paginated:\", gunbot.pnl_daily_paginated(\n        \"binance/USDT-BTC\", 1, 30, ts()\n    ))\n    print(\"pnl_sum:\", gunbot.pnl_sum(\"binance\", ts(days=-7), ts()))\n    print(\"pnl_total:\", gunbot.pnl_total(\"binance/USDT-BTC\"))\n\n    print(\"pnl_overview:\", gunbot.pnl_overview(body={\n        \"timezone\": \"Europe/Berlin\",\n        \"keys\": [\"binance/USDT-BTC\"],\n    }))\n\n    # ---------- FILES ----------\n    print(\"files_state:\", gunbot.files_state())\n    print(\"files_strategy:\", gunbot.files_strategy())\n\n    print(\"files_strategy_write:\", gunbot.files_strategy_write(body={\n        \"filename\": \"apistrat.js\",\n        \"document\": \"full strategy as string\",\n    }))\n\n    print(\"files_strategy_delete:\", gunbot.files_strategy_delete(body={\n        \"filename\": \"apistrat.js\",\n    }))\n\n    print(\"files_strategy_get:\", gunbot.files_strategy_get(body={\n        \"filename\": \"mfi.js\",\n    }))\n\n    print(\"files_acvar_get:\", gunbot.files_acvar_get(body={\n        \"filename\": \"autoconfig-variables.json\",\n    }))\n\n    print(\"files_acvar:\", gunbot.files_acvar())\n\n    print(\"files_autoconfig_write:\", gunbot.files_autoconfig_write(body={\n        # \"document\": {...}\n    }))\n\n    print(\"files_custom_editor_write:\", gunbot.files_custom_editor_write(body={\n        \"document\": {\"test\": True},\n    }))\n\n    print(\"files_custom_editor_get:\", gunbot.files_custom_editor_get())\n    print(\"files_backup:\", gunbot.files_backup())\n\n    print(\"files_backup_get:\", gunbot.files_backup_get(body={\n        \"filename\": \"autoconfig.json.1623252417412\",\n    }))\n\n    # ---------- TRADING ----------\n    print(\"trade_buy:\", gunbot.trade_buy(body={\n        \"exch\": \"binance\",\n        \"pair\": \"USDT-BTC\",\n        \"price\": 100000,\n        \"amt\": 0.001,\n    }))\n\n    print(\"trade_sell:\", gunbot.trade_sell(body={\n        \"exch\": \"binance\",\n        \"pair\": \"USDT-BTC\",\n        \"price\": 100000,\n        \"amt\": 0.001,\n    }))\n\n    print(\"trade_buy_market:\", gunbot.trade_buy_market(body={\n        \"exch\": \"binance\",\n        \"pair\": \"USDT-BTC\",\n        \"price\": 100000,     # 0 if live trading\n        \"amt\": 0.001,\n    }))\n\n    print(\"trade_sell_market:\", gunbot.trade_sell_market(body={\n        \"exch\": \"binance\",\n        \"pair\": \"USDT-BTC\",\n        \"price\": 100000,\n        \"amt\": 0.001,\n    }))\n\n\nif __name__ == \"__main__\":\n    main()\n\n```\n\n---\n\n## Troubleshooting\n\n| Symptom             | Checklist                                          |\n| ------------------- | -------------------------------------------------- |\n| 401 Unauthorized    | ✓ Valid token? ✓ Correct `base_path`?              |\n| 400 Bad Request     | ✓ Payload shape vs spec? ✓ Missing required param? |\n| `ConnectionRefused` | ✓ Gunbot core running? ✓ Port forwarded/open?      |\n\nSet environment variable `GUNBOT_SDK_DEBUG=1` for verbose request/response logs.\n\n---\n\n## Contributing\n\n1. Fork → PR\n2. Follow Conventional Commits for commits \u0026 PR titles\n\n---\n\n## License\n\nMIT – see [`LICENSE`](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgunthardeniro%2Fgunbot-sdk-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgunthardeniro%2Fgunbot-sdk-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgunthardeniro%2Fgunbot-sdk-python/lists"}