pybinbot 0.1.6__py3-none-any.whl

models/bot_base.py

@@ -0,0 +1,99 @@
+from pydantic import BaseModel, Field, field_validator
+from shared.types import Amount
+from shared.timestamps import timestamp
+from shared.enums import (
+    QuoteAssets,
+    BinanceKlineIntervals,
+    CloseConditions,
+    Status,
+    Strategy,
+)
+from shared.timestamps import ts_to_humandate
+
+
+class BotBase(BaseModel):
+    pair: str
+    fiat: str = Field(default="USDC")
+    quote_asset: QuoteAssets = Field(default=QuoteAssets.USDC)
+    fiat_order_size: Amount = Field(
+        default=0, ge=0, description="Min Binance 0.0001 BNB approx 15USD"
+    )
+    candlestick_interval: BinanceKlineIntervals = Field(
+        default=BinanceKlineIntervals.fifteen_minutes
+    )
+    close_condition: CloseConditions = Field(default=CloseConditions.dynamic_trailling)
+    cooldown: int = Field(
+        default=0,
+        ge=0,
+        description="cooldown period in minutes before opening next bot with same pair",
+    )
+    created_at: float = Field(default_factory=timestamp)
+    updated_at: float = Field(default_factory=timestamp)
+    dynamic_trailling: bool = Field(default=False)
+    logs: list = Field(default=[])
+    mode: str = Field(default="manual")
+    name: str = Field(
+        default="terminal",
+        description="Algorithm name or 'terminal' if executed from React app",
+    )
+    status: Status = Field(default=Status.inactive)
+    stop_loss: Amount = Field(
+        default=0, ge=-1, le=101, description="If stop_loss > 0, allow for reversal"
+    )
+    margin_short_reversal: bool = Field(
+        default=False,
+        description="Autoswitch from long to short or short to long strategy",
+    )
+    take_profit: Amount = Field(default=0, ge=-1, le=101)
+    trailling: bool = Field(default=False)
+    trailling_deviation: Amount = Field(
+        default=0,
+        ge=-1,
+        le=101,
+        description="Trailling activation (first take profit hit)",
+    )
+    trailling_profit: Amount = Field(default=0, ge=-1, le=101)
+    strategy: Strategy = Field(default=Strategy.long)
+    model_config = {
+        "from_attributes": True,
+        "use_enum_values": True,
+        "json_schema_extra": {
+            "description": "Most fields are optional. Deal and orders fields are generated internally and filled by Exchange",
+            "examples": [
+                {
+                    "pair": "BNBUSDT",
+                    "fiat": "USDC",
+                    "quote_asset": "USDC",
+                    "fiat_order_size": 15,
+                    "candlestick_interval": "15m",
+                    "close_condition": "dynamic_trailling",
+                    "cooldown": 0,
+                    "created_at": 1702999999.0,
+                    "updated_at": 1702999999.0,
+                    "dynamic_trailling": False,
+                    "logs": [],
+                    "mode": "manual",
+                    "name": "Default bot",
+                    "status": "inactive",
+                    "stop_loss": 0,
+                    "take_profit": 2.3,
+                    "trailling": True,
+                    "trailling_deviation": 0.63,
+                    "trailling_profit": 2.3,
+                    "margin_short_reversal": False,
+                    "strategy": "long",
+                }
+            ],
+        },
+    }
+
+    @field_validator("pair")
+    @classmethod
+    def check_pair_not_empty(cls, v):
+        assert v != "", "Pair field must be filled."
+        return v
+
+    def add_log(self, message: str) -> str:
+        timestamped_message = f"[{ts_to_humandate(timestamp())}] {message}"
+        self.logs.append(timestamped_message)
+        return self.logs[-1]

models/deal.py

@@ -0,0 +1,70 @@
+from pydantic import BaseModel, Field, field_validator
+from shared.types import Amount
+
+
+class DealBase(BaseModel):
+    """
+    Data model that is used for operations,
+    so it should all be numbers (int or float)
+    """
+
+    base_order_size: Amount = Field(default=0, gt=-1)
+    current_price: Amount = Field(default=0)
+    take_profit_price: Amount = Field(default=0)
+    trailling_stop_loss_price: Amount = Field(
+        default=0,
+        description="take_profit but for trailling, to avoid confusion, trailling_profit_price always be > trailling_stop_loss_price",
+    )
+    trailling_profit_price: Amount = Field(default=0)
+    stop_loss_price: Amount = Field(default=0)
+
+    # fields for margin trading
+    total_interests: float = Field(default=0, gt=-1)
+    total_commissions: float = Field(default=0, gt=-1)
+    margin_loan_id: int = Field(
+        default=0,
+        ge=0,
+        description="Txid from Binance. This is used to check if there is a loan, 0 means no loan",
+    )
+    margin_repay_id: int = Field(
+        default=0, ge=0, description="= 0, it has not been repaid"
+    )
+
+    # Refactored deal prices that combine both margin and spot
+    opening_price: Amount = Field(
+        default=0,
+        description="replaces previous buy_price or short_sell_price/margin_short_sell_price",
+    )
+    opening_qty: Amount = Field(
+        default=0,
+        description="replaces previous buy_total_qty or short_sell_qty/margin_short_sell_qty",
+    )
+    opening_timestamp: int = Field(default=0)
+    closing_price: Amount = Field(
+        default=0,
+        description="replaces previous sell_price or short_sell_price/margin_short_sell_price",
+    )
+    closing_qty: Amount = Field(
+        default=0,
+        description="replaces previous sell_qty or short_sell_qty/margin_short_sell_qty",
+    )
+    closing_timestamp: int = Field(
+        default=0,
+        description="replaces previous buy_timestamp or margin/short_sell timestamps",
+    )
+
+    @field_validator("margin_loan_id", mode="before")
+    @classmethod
+    def validate_margin_loan_id(cls, value):
+        if isinstance(value, float):
+            return int(value)
+        else:
+            return value
+
+    @field_validator("margin_loan_id", mode="after")
+    @classmethod
+    def cast_float(cls, value):
+        if isinstance(value, float):
+            return int(value)
+        else:
+            return value

models/order.py

@@ -0,0 +1,104 @@
+from pydantic import BaseModel, Field, field_validator
+from shared.types import Amount
+from shared.enums import (
+    DealType,
+    OrderStatus,
+)
+
+
+class OrderBase(BaseModel):
+    order_type: str = Field(
+        description="Because every exchange has different naming, we should keep it as a str rather than OrderType enum"
+    )
+    time_in_force: str
+    timestamp: int = Field(default=0)
+    order_id: int | str = Field(
+        description="Because every exchange has id type, we should keep it as looose as possible. Int is for backwards compatibility"
+    )
+    order_side: str = Field(
+        description="Because every exchange has different naming, we should keep it as a str rather than OrderType enum"
+    )
+    pair: str
+    qty: float
+    status: OrderStatus
+    price: float
+    deal_type: DealType
+    model_config = {
+        "from_attributes": True,
+        "use_enum_values": True,
+        "json_schema_extra": {
+            "description": "Most fields are optional. Deal field is generated internally, orders are filled up by Exchange",
+            "examples": [
+                {
+                    "order_type": "LIMIT",
+                    "time_in_force": "GTC",
+                    "timestamp": 0,
+                    "order_id": 0,
+                    "order_side": "BUY",
+                    "pair": "",
+                    "qty": 0,
+                    "status": "",
+                    "price": 0,
+                }
+            ],
+        },
+    }
+
+
+class DealModel(BaseModel):
+    base_order_size: Amount = Field(default=0, gt=-1)
+    current_price: Amount = Field(default=0)
+    take_profit_price: Amount = Field(default=0)
+    trailling_stop_loss_price: Amount = Field(
+        default=0,
+        description="take_profit but for trailling, to avoid confusion, trailling_profit_price always be > trailling_stop_loss_price",
+    )
+    trailling_profit_price: Amount = Field(default=0)
+    stop_loss_price: Amount = Field(default=0)
+    total_interests: float = Field(default=0, gt=-1)
+    total_commissions: float = Field(default=0, gt=-1)
+    margin_loan_id: int = Field(
+        default=0,
+        ge=0,
+        description="Txid from Binance. This is used to check if there is a loan, 0 means no loan",
+    )
+    margin_repay_id: int = Field(
+        default=0, ge=0, description="= 0, it has not been repaid"
+    )
+    opening_price: Amount = Field(
+        default=0,
+        description="replaces previous buy_price or short_sell_price/margin_short_sell_price",
+    )
+    opening_qty: Amount = Field(
+        default=0,
+        description="replaces previous buy_total_qty or short_sell_qty/margin_short_sell_qty",
+    )
+    opening_timestamp: int = Field(default=0)
+    closing_price: Amount = Field(
+        default=0,
+        description="replaces previous sell_price or short_sell_price/margin_short_sell_price",
+    )
+    closing_qty: Amount = Field(
+        default=0,
+        description="replaces previous sell_qty or short_sell_qty/margin_short_sell_qty",
+    )
+    closing_timestamp: int = Field(
+        default=0,
+        description="replaces previous buy_timestamp or margin/short_sell timestamps",
+    )
+
+    @field_validator("margin_loan_id", mode="before")
+    @classmethod
+    def validate_margin_loan_id(cls, value):
+        if isinstance(value, float):
+            return int(value)
+        else:
+            return value
+
+    @field_validator("margin_loan_id", mode="after")
+    @classmethod
+    def cast_float(cls, value):
+        if isinstance(value, float):
+            return int(value)
+        else:
+            return value

models/signals.py

@@ -0,0 +1,51 @@
+from pydantic import BaseModel, Field, field_validator, ConfigDict
+from typing import Optional
+from datetime import datetime
+
+
+# Example shared model (copy actual model code from source files)
+class HABollinguerSpread(BaseModel):
+    """
+    Pydantic model for the Bollinguer spread.
+    (optional)
+    """
+
+    bb_high: float
+    bb_mid: float
+    bb_low: float
+
+
+class SignalsConsumer(BaseModel):
+    """
+    Pydantic model for the signals consumer.
+    """
+
+    type: str = Field(default="signal")
+    date: str = Field(
+        default_factory=lambda: datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    )
+    spread: Optional[float] = Field(default=0)
+    current_price: Optional[float] = Field(default=0)
+    msg: str
+    symbol: str
+    algo: str
+    bot_strategy: str = Field(default="long")
+    bb_spreads: Optional[HABollinguerSpread]
+    autotrade: bool = Field(default=True, description="If it is in testing mode, False")
+
+    model_config = ConfigDict(
+        extra="allow",
+        use_enum_values=True,
+    )
+
+    @field_validator("spread", "current_price")
+    @classmethod
+    def name_must_contain_space(cls, v):
+        if v is None:
+            return 0
+        elif isinstance(v, str):
+            return float(v)
+        elif isinstance(v, float):
+            return v
+        else:
+            raise ValueError("must be a float or 0")

pybinbot-0.1.6.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: pybinbot
+Version: 0.1.6
+Summary: Utility functions for the binbot project.
+Author-email: Carlos Wu <carkodw@gmail.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic[email]>=2.0.0
+Requires-Dist: numpy==2.2.0
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pymongo==4.6.3
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# PyBinbot
+
+Utility functions for the binbot project. Most of the code here is not runnable, there's no server or individual scripts, you simply move code to here when it's used in both binbot and binquant.
+
+``pybinbot`` is the public API module for the distribution.
+
+This module re-exports the internal ``shared`` and ``models`` packages and the most commonly used helpers and enums so consumers can simply::
+
+        from pybinbot import round_numbers, ExchangeId
+
+The implementation deliberately avoids importing heavy third-party libraries at module import time.
+
+
+## Installation
+
+```bash
+uv sync --extra dev
+```
+
+`--extra dev` also installs development tools like ruff and mypy
+
+
+## Publishing
+
+```bash
+make bump-patch
+```
+or 
+
+```bash
+make bump-minor
+```
+
+or
+
+```bash
+make bump-major
+```
+
+For further commands take a look at the `Makefile` such as testing `make test`

pybinbot-0.1.6.dist-info/RECORD

@@ -0,0 +1,15 @@
+pybinbot.py,sha256=bLB9AYwuk3cbQ7HVlVGwTtzqNSV3FsZv4Rtbetg0Kas,1920
+models/bot_base.py,sha256=z9hSK7uVLW4oDmPdtntYozo8RnQnpZtFi8fL1r9Qd5Q,3593
+models/deal.py,sha256=jOdMSobN_K4-be3hG38l0WeZq5ln5JndA-BBgMUElsI,2402
+models/order.py,sha256=FHs7qi2JNYn-kXfWD2m5oFSSeMQDKmw0uPDwOvy5KkQ,3592
+models/signals.py,sha256=DAcV2ft6n5iJW4kqspdfEakFZ3igx97erwyTiyDMlgM,1356
+pybinbot-0.1.6.dist-info/licenses/LICENSE,sha256=ECEAqAQ81zTT8PeN7gYqbkZtewkyeleEqQ26MxuHQxs,938
+shared/enums.py,sha256=b472TAbRrnznDRDDVrLW_2I_9dURafqeC3pMu4DHQ1w,6730
+shared/logging_config.py,sha256=XZblKXH9KsLUDbIJqFRZPzI0h17-CRBZH4KktVak-TI,1144
+shared/maths.py,sha256=JjlrgV0INlJG4Zj28ahRkfzcI2Ec4noilrDwX2p82TM,3207
+shared/timestamps.py,sha256=401JkggjW--trNenxkUBEObnWyy9Cd-L3xVpqdbW8Tc,2587
+shared/types.py,sha256=KfuJzjsbMUHFcBaQ6ZXUbuSyFHbHqehgeY73Zt8lqO8,173
+pybinbot-0.1.6.dist-info/METADATA,sha256=LEBxxxJ0TBmDQ77xJpskIZYprx8_5y52oRgDFxsRf60,1358
+pybinbot-0.1.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pybinbot-0.1.6.dist-info/top_level.txt,sha256=rfaU2KRcKvquGQYwN5weorBMzgHpWW4eZlITOQwjRvw,23
+pybinbot-0.1.6.dist-info/RECORD,,

pybinbot-0.1.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pybinbot-0.1.6.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pybinbot-0.1.6.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+models
+pybinbot
+shared

pybinbot.py

@@ -0,0 +1,93 @@
+from shared.maths import (
+    supress_trailling,
+    round_numbers,
+    round_numbers_ceiling,
+    round_numbers_floor,
+    supress_notation,
+    interval_to_millisecs,
+    format_ts,
+    zero_remainder,
+)
+from shared.timestamps import (
+    timestamp,
+    round_timestamp,
+    ts_to_day,
+    ms_to_sec,
+    sec_to_ms,
+    ts_to_humandate,
+    timestamp_to_datetime,
+)
+from shared.enums import (
+    CloseConditions,
+    KafkaTopics,
+    DealType,
+    BinanceOrderModel,
+    Status,
+    Strategy,
+    OrderType,
+    TimeInForce,
+    OrderSide,
+    OrderStatus,
+    TrendEnum,
+    BinanceKlineIntervals,
+    KucoinKlineIntervals,
+    AutotradeSettingsDocument,
+    UserRoles,
+    QuoteAssets,
+    ExchangeId,
+    MarketDominance,
+)
+from shared.types import Amount
+from shared.logging_config import configure_logging
+from models.bot_base import BotBase
+from models.order import OrderBase
+from models.deal import DealBase
+from models.signals import HABollinguerSpread, SignalsConsumer
+
+__all__ = [
+    # models
+    "BotBase",
+    "OrderBase",
+    "DealBase",
+    # misc
+    "Amount",
+    "configure_logging",
+    # maths helpers
+    "supress_trailling",
+    "round_numbers",
+    "round_numbers_ceiling",
+    "round_numbers_floor",
+    "supress_notation",
+    "interval_to_millisecs",
+    "format_ts",
+    "zero_remainder",
+    # timestamp helpers
+    "timestamp",
+    "round_timestamp",
+    "ts_to_day",
+    "ms_to_sec",
+    "sec_to_ms",
+    "ts_to_humandate",
+    "timestamp_to_datetime",
+    # enums
+    "CloseConditions",
+    "KafkaTopics",
+    "DealType",
+    "BinanceOrderModel",
+    "Status",
+    "Strategy",
+    "OrderType",
+    "TimeInForce",
+    "OrderSide",
+    "OrderStatus",
+    "TrendEnum",
+    "BinanceKlineIntervals",
+    "KucoinKlineIntervals",
+    "AutotradeSettingsDocument",
+    "UserRoles",
+    "QuoteAssets",
+    "ExchangeId",
+    "HABollinguerSpread",
+    "SignalsConsumer",
+    "MarketDominance",
+]

shared/enums.py

@@ -0,0 +1,272 @@
+from enum import Enum
+from pydantic import BaseModel, field_validator
+
+
+class CloseConditions(str, Enum):
+    dynamic_trailling = "dynamic_trailling"
+    # No trailling, standard stop loss
+    timestamp = "timestamp"
+    # binbot-research param (self.market_trend_reversal)
+    market_reversal = "market_reversal"
+
+
+class KafkaTopics(str, Enum):
+    klines_store_topic = "klines-store-topic"
+    technical_indicators = "technical-indicators"
+    signals = "signals"
+    restart_streaming = "restart-streaming"
+    restart_autotrade = "restart-autotrade"
+
+
+class DealType(str, Enum):
+    base_order = "base_order"
+    take_profit = "take_profit"
+    stop_loss = "stop_loss"
+    short_sell = "short_sell"
+    short_buy = "short_buy"
+    margin_short = "margin_short"
+    panic_close = "panic_close"
+
+
+class BinanceOrderModel(BaseModel):
+    """
+    Data model given by Binance,
+    therefore it should be strings
+    """
+
+    order_type: str
+    time_in_force: str
+    timestamp: int
+    order_id: int
+    order_side: str
+    pair: str
+    qty: float
+    status: str
+    price: float
+    deal_type: DealType
+
+    @field_validator("timestamp", "order_id", "price", "qty", "order_id")
+    @classmethod
+    def validate_str_numbers(cls, v):
+        if isinstance(v, float):
+            return v
+        elif isinstance(v, int):
+            return v
+        elif isinstance(v, str):
+            return float(v)
+        else:
+            raise ValueError(f"{v} must be a number")
+
+
+class Status(str, Enum):
+    all = "all"
+    inactive = "inactive"
+    active = "active"
+    completed = "completed"
+    error = "error"
+
+
+class Strategy(str, Enum):
+    long = "long"
+    margin_short = "margin_short"
+
+
+class OrderType(str, Enum):
+    limit = "LIMIT"
+    market = "MARKET"
+    stop_loss = "STOP_LOSS"
+    stop_loss_limit = "STOP_LOSS_LIMIT"
+    take_profit = "TAKE_PROFIT"
+    take_profit_limit = "TAKE_PROFIT_LIMIT"
+    limit_maker = "LIMIT_MAKER"
+
+
+class TimeInForce(str, Enum):
+    gtc = "GTC"
+    ioc = "IOC"
+    fok = "FOK"
+
+
+class OrderSide(str, Enum):
+    buy = "BUY"
+    sell = "SELL"
+
+
+class OrderStatus(str, Enum):
+    """
+    Must be all uppercase for SQL alchemy
+    and Alembic to do migration properly
+    """
+
+    NEW = "NEW"
+    PARTIALLY_FILLED = "PARTIALLY_FILLED"
+    FILLED = "FILLED"
+    CANCELED = "CANCELED"
+    REJECTED = "REJECTED"
+    EXPIRED = "EXPIRED"
+
+
+class TrendEnum(str, Enum):
+    up_trend = "uptrend"
+    down_trend = "downtrend"
+    neutral = None
+
+
+class DealType(str, Enum):
+    base_order = "base_order"
+    take_profit = "take_profit"
+    stop_loss = "stop_loss"
+    short_sell = "short_sell"
+    short_buy = "short_buy"
+    margin_short = "margin_short"
+    panic_close = "panic_close"
+    trailling_profit = "trailling_profit"
+    conversion = "conversion"  # converts one crypto to another
+
+
+class BinanceKlineIntervals(str, Enum):
+    one_minute = "1m"
+    three_minutes = "3m"
+    five_minutes = "5m"
+    fifteen_minutes = "15m"
+    thirty_minutes = "30m"
+    one_hour = "1h"
+    two_hours = "2h"
+    four_hours = "4h"
+    six_hours = "6h"
+    eight_hours = "8h"
+    twelve_hours = "12h"
+    one_day = "1d"
+    three_days = "3d"
+    one_week = "1w"
+    one_month = "1M"
+
+    def bin_size(self):
+        return int(self.value[:-1])
+
+    def unit(self):
+        if self.value[-1:] == "m":
+            return "minute"
+        elif self.value[-1:] == "h":
+            return "hour"
+        elif self.value[-1:] == "d":
+            return "day"
+        elif self.value[-1:] == "w":
+            return "week"
+        elif self.value[-1:] == "M":
+            return "month"
+
+    def to_kucoin_interval(self) -> str:
+        """
+        Convert Binance interval format to Kucoin interval format.
+
+        Binance: 1m, 5m, 15m, 1h, 4h, 1d, 1w
+        Kucoin: 1min, 5min, 15min, 1hour, 4hour, 1day, 1week
+        """
+        interval_map = {
+            "1m": "1min",
+            "3m": "3min",
+            "5m": "5min",
+            "15m": "15min",
+            "30m": "30min",
+            "1h": "1hour",
+            "2h": "2hour",
+            "4h": "4hour",
+            "6h": "6hour",
+            "8h": "8hour",
+            "12h": "12hour",
+            "1d": "1day",
+            "3d": "3day",
+            "1w": "1week",
+            "1M": "1month",
+        }
+        return interval_map.get(self.value, self.value)
+
+
+class KucoinKlineIntervals(str, Enum):
+    ONE_MINUTE = "1min"
+    THREE_MINUTES = "3min"
+    FIVE_MINUTES = "5min"
+    FIFTEEN_MINUTES = "15min"
+    THIRTY_MINUTES = "30min"
+    ONE_HOUR = "1hour"
+    TWO_HOURS = "2hour"
+    FOUR_HOURS = "4hour"
+    SIX_HOURS = "6hour"
+    EIGHT_HOURS = "8hour"
+    TWELVE_HOURS = "12hour"
+    ONE_DAY = "1day"
+    ONE_WEEK = "1week"
+
+    # Helper to calculate interval duration in milliseconds
+    def get_interval_ms(interval_str: str) -> int:
+        """Convert Kucoin interval string to milliseconds"""
+        interval_map = {
+            "1min": 60 * 1000,
+            "3min": 3 * 60 * 1000,
+            "5min": 5 * 60 * 1000,
+            "15min": 15 * 60 * 1000,
+            "30min": 30 * 60 * 1000,
+            "1hour": 60 * 60 * 1000,
+            "2hour": 2 * 60 * 60 * 1000,
+            "4hour": 4 * 60 * 60 * 1000,
+            "6hour": 6 * 60 * 60 * 1000,
+            "8hour": 8 * 60 * 60 * 1000,
+            "12hour": 12 * 60 * 60 * 1000,
+            "1day": 24 * 60 * 60 * 1000,
+            "1week": 7 * 24 * 60 * 60 * 1000,
+        }
+        return interval_map.get(interval_str, 60 * 1000)  # Default to 1 minute
+
+
+class AutotradeSettingsDocument(str, Enum):
+    # Autotrade settings for test bots
+    test_autotrade_settings = "test_autotrade_settings"
+    # Autotrade settings for real bots
+    settings = "autotrade_settings"
+
+
+class UserRoles(str, Enum):
+    # Full access to all resources
+    user = "user"
+    # Access to terminal and customer accounts
+    admin = "admin"
+    # Only access to funds and client website
+    customer = "customer"
+
+
+class QuoteAssets(str, Enum):
+    """
+    Quote assets supported by Binbot orders
+    Includes both crypto assets and fiat currencies
+    """
+
+    # Crypto assets
+    USDT = "USDT"
+    USDC = "USDC"
+    BTC = "BTC"
+    ETH = "ETH"
+    # Backwards compatibility
+    TRY = "TRY"
+
+    def is_fiat(self) -> bool:
+        """Check if the asset is a fiat currency"""
+        return self.value in ["TRY", "EUR", "USD"]
+
+    @classmethod
+    def get_fiat_currencies(cls) -> list["QuoteAssets"]:
+        """
+        Get all fiat currencies
+        """
+        return [asset for asset in cls if asset.is_fiat()]
+
+
+class ExchangeId(str, Enum):
+    KUCOIN = "kucoin"
+    BINANCE = "binance"
+
+
+class MarketDominance(str, Enum):
+    NEUTRAL = "neutral"
+    GAINERS = "gainers"
+    LOSERS = "losers"

shared/logging_config.py

@@ -0,0 +1,42 @@
+import logging
+import os
+import time
+from typing import Iterable
+
+DEFAULT_FORMAT = "%(asctime)s.%(msecs)03d UTC %(levelname)s %(name)s: %(message)s"
+DEFAULT_DATEFMT = "%Y-%m-%d %H:%M:%S"
+
+
+def configure_logging(
+    *,
+    level: str | None = None,
+    fmt: str = DEFAULT_FORMAT,
+    datefmt: str = DEFAULT_DATEFMT,
+    utc: bool = True,
+    force: bool = True,
+    quiet_loggers: Iterable[str] | None = ("uvicorn", "confluent_kafka"),
+) -> None:
+    """
+    Configure root logging consistently across API services.
+    """
+    resolved_level = str(level or os.environ.get("LOG_LEVEL", "INFO")).upper()
+    logging.basicConfig(
+        level=resolved_level,
+        format=fmt,
+        datefmt=datefmt,
+        force=force,
+    )
+    if utc:
+        logging.Formatter.converter = time.gmtime
+
+    if quiet_loggers:
+        quiet_level = os.environ.get("QUIET_LIB_LOG_LEVEL", "WARNING").upper()
+        for name in quiet_loggers:
+            logging.getLogger(name).setLevel(quiet_level)
+
+    logging.getLogger(__name__).debug(
+        "Logging configured (level=%s, utc=%s, force=%s)",
+        resolved_level,
+        utc,
+        force,
+    )

shared/maths.py

@@ -0,0 +1,123 @@
+import math
+import re
+from decimal import Decimal
+from datetime import datetime
+from typing import cast
+
+
+def ensure_float(value: str | int | float) -> float:
+    if isinstance(value, str) or isinstance(value, int):
+        return float(value)
+
+    return value
+
+
+def supress_trailling(value: str | float | int) -> float:
+    """
+    Supress trailing 0s without changing the numeric value.
+
+    Also attempts to normalise away scientific notation for small
+    numbers while preserving the original value.
+    """
+    # Use Decimal(str(value)) to avoid binary float rounding issues
+    dec = Decimal(str(value))
+    # Normalise to remove redundant trailing zeros while preserving value
+    dec = dec.normalize()
+    return float(dec)
+
+
+def round_numbers(value: float | int, decimals=6) -> float | int:
+    decimal_points = 10 ** int(decimals)
+    number = float(value)
+    result = math.floor(number * decimal_points) / decimal_points
+    if decimals == 0:
+        result = int(result)
+    return result
+
+
+def round_numbers_ceiling(value, decimals=6):
+    decimal_points = 10 ** int(decimals)
+    number = float(value)
+    result = math.ceil(number * decimal_points) / decimal_points
+    if decimals == 0:
+        result = int(result)
+    return float(result)
+
+
+def round_numbers_floor(value, decimals=6):
+    decimal_points = 10 ** int(decimals)
+    number = float(value)
+    result = math.floor(number * decimal_points) / decimal_points
+    if decimals == 0:
+        result = int(result)
+    return float(result)
+
+
+def supress_notation(num: float, precision: int = 0) -> str:
+    """
+    Supress scientific notation and return a fixed-point string.
+
+    Examples
+    -------
+    8e-5  -> "0.00008" (precision=5)
+    123.456, precision=2 -> "123.46"
+    """
+    dec = Decimal(str(num))
+
+    if precision >= 0:
+        # Quantize to the requested number of decimal places using
+        # Decimal's standard rounding (half even by default).
+        quant = Decimal(1).scaleb(-precision)  # 10**-precision
+        dec = dec.quantize(quant)
+        decimal_points = precision
+    else:
+        # Let Decimal decide the scale, then format with all significant
+        # decimal places.
+        dec = dec.normalize()
+        exp = cast(int, dec.as_tuple().exponent)
+        decimal_points = -exp
+
+    return f"{dec:.{decimal_points}f}"
+
+
+def interval_to_millisecs(interval: str) -> int:
+    time, notation = re.findall(r"[A-Za-z]+|\d+", interval)
+    if notation == "m":
+        # minutes
+        return int(time) * 60 * 1000
+
+    if notation == "h":
+        # hours
+        return int(time) * 60 * 60 * 1000
+
+    if notation == "d":
+        # day
+        return int(time) * 24 * 60 * 60 * 1000
+
+    if notation == "w":
+        # weeks
+        return int(time) * 5 * 24 * 60 * 60 * 1000
+
+    if notation == "M":
+        # month
+        return int(time) * 30 * 24 * 60 * 60 * 1000
+
+    return 0
+
+
+def format_ts(time: datetime) -> str:
+    """
+    Central place to format datetime
+    to human-readable date
+    """
+    return time.strftime("%Y-%m-%d %H:%M:%S.%f")
+
+
+def zero_remainder(x):
+    number = x
+
+    while True:
+        if number % x == 0:
+            return number
+        else:
+            number += x

shared/timestamps.py

@@ -0,0 +1,97 @@
+import os
+from time import time
+import math
+from zoneinfo import ZoneInfo
+from shared.maths import round_numbers_ceiling
+from datetime import datetime
+
+format = "%Y-%m-%d %H:%M:%S"
+
+def timestamp() -> int:
+    ts = time() * 1000
+    rounded_ts = round_timestamp(ts)
+    return rounded_ts
+
+
+def round_timestamp(ts: int | float) -> int:
+    """
+    Round (or trim) millisecond timestamps to at most 13 digits.
+
+    For realistic millisecond timestamps (13 digits) this is a no-op.
+    For larger integers, extra lower-order digits are discarded so that
+    the result has exactly 13 digits.
+    """
+    ts_int = int(ts)
+    digits = int(math.log10(ts_int)) + 1 if ts_int > 0 else 1
+
+    if digits > 13:
+        # Drop extra lower-order digits to get back to 13 digits.
+        decimals = digits - 13
+        factor = 10**decimals
+        return ts_int // factor
+    else:
+        return ts_int
+
+
+def ts_to_day(ts: float | int) -> str:
+    """
+    Convert timestamp to date (day) format YYYY-MM-DD
+    """
+    digits = int(math.log10(ts)) + 1
+    if digits >= 10:
+        ts = ts // pow(10, digits - 10)
+    else:
+        ts = ts * pow(10, 10 - digits)
+
+    dt_obj = datetime.fromtimestamp(ts)
+    b_str_date = datetime.strftime(dt_obj, format)
+    return b_str_date
+
+
+def ms_to_sec(ms: int) -> int:
+    """
+    JavaScript needs 13 digits (milliseconds)
+    for new Date() to parse timestamps
+    correctly
+    """
+    return ms // 1000
+
+
+def sec_to_ms(sec: int) -> int:
+    """
+    Python datetime needs 10 digits (seconds)
+    to parse dates correctly from timestamps
+    """
+    return sec * 1000
+
+
+def ts_to_humandate(ts: int) -> str:
+    """Convert timestamp to human-readable date.
+
+    Accepts either seconds (10 digits) or milliseconds (13 digits) and
+    normalises to seconds for ``datetime.fromtimestamp``.
+    """
+    if len(str(abs(ts))) > 10:
+        # if timestamp is in milliseconds
+        ts = ts // 1000
+    return datetime.fromtimestamp(ts).strftime(format)
+
+
+def timestamp_to_datetime(timestamp: str | int) -> str:
+    """
+    Convert a timestamp in milliseconds to seconds
+    to match expectation of datetime
+    Then convert to a human readable format.
+
+    Parameters
+    ----------
+    timestamp : str | int
+        The timestamp in milliseconds. Always in London timezone
+        to avoid inconsistencies across environments (Github, prod, local)
+    """
+    timestamp = int(round_numbers_ceiling(int(timestamp) / 1000, 0))
+    dt = datetime.fromtimestamp(
+        timestamp, tz=ZoneInfo(os.getenv("TZ", "Europe/London"))
+    )
+    return dt.strftime(format)
+    

shared/types.py

@@ -0,0 +1,8 @@
+from typing import Annotated
+from pydantic import BeforeValidator
+from shared.maths import ensure_float
+
+Amount = Annotated[
+    float,
+    BeforeValidator(ensure_float),
+]