pybinbot 0.0.1__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/order.py

@@ -0,0 +1,130 @@
+from typing import List, Optional
+from uuid import uuid4, UUID
+from pydantic import BaseModel, Field, field_validator
+from databases.utils import Amount, timestamp
+from tools.enum_definitions import (
+    QuoteAssets,
+    BinanceKlineIntervals,
+    CloseConditions,
+    Status,
+    Strategy,
+    DealType,
+    OrderStatus,
+)
+from tools.handle_error import IResponseBase
+from tools.maths import ts_to_humandate
+from databases.tables.bot_table import BotTable, PaperTradingTable
+from databases.tables.deal_table import DealTable
+from databases.tables.order_table import ExchangeOrderTable
+
+
+class OrderModel(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,
+                }
+            ],
+        },
+    }
+
+    @classmethod
+    def dump_from_table(cls, bot):
+        if isinstance(bot, BotTable) or isinstance(bot, PaperTradingTable):
+            model = BotModel.model_construct(**bot.model_dump())
+            deal_model = DealModel.model_construct(**bot.deal.model_dump())
+            order_models = [
+                OrderModel.model_construct(**order.model_dump()) for order in bot.orders
+            ]
+            model.deal = deal_model
+            model.orders = order_models
+            return model
+        else:
+            return bot
+
+
+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,60 @@
+"""
+Shared Pydantic models for Binquant and Binbot.
+This file is auto-generated and should be reviewed for deduplication and refactoring.
+"""
+
+# Example imports (update as needed)
+from pydantic import BaseModel, Field, EmailStr, field_validator, ConfigDict
+from typing import Optional, List, Sequence, Union
+from uuid import UUID, uuid4
+from datetime import datetime
+
+# ...existing code...
+
+
+# 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.0.1.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: pybinbot
+Version: 0.0.1
+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: aiokafka>=0.12.0
+Requires-Dist: apscheduler>=3.6.3
+Requires-Dist: confluent-kafka>=2.11.1
+Requires-Dist: kafka-python>=2.0.2
+Requires-Dist: kucoin-universal-sdk>=1.3.0
+Requires-Dist: numpy==2.2.0
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: passlib
+Requires-Dist: pydantic[email]>=2.0.0
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pymongo>=4.6.3
+Requires-Dist: python-dotenv
+Requires-Dist: python-jose
+Requires-Dist: requests>=2.28.1
+Requires-Dist: requests-cache>=1.2.0
+Requires-Dist: requests-html>=0.10.0
+Requires-Dist: scipy==1.14.1
+Requires-Dist: websocket-client>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# binbot-utils
+
+Utility functions for the binbot project.
+
+## Installation
+
+```bash
+uv sync
+```
+
+## Usage
+
+Import and use the utilities in your Python code.
+
+## Publishing
+
+To build and upload to PyPI:
+
+```bash
+python -m build
+python -m twine upload dist/*
+```

pybinbot-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+models/bot_base.py,sha256=z9hSK7uVLW4oDmPdtntYozo8RnQnpZtFi8fL1r9Qd5Q,3593
+models/order.py,sha256=pQbL2rpgXvmkqiwpKwVFkuJnn3i1QR-omuc4E5eDWsk,4573
+models/signals.py,sha256=DZc2r9x9XouRu9u14wI-zVEBX23-7wn_-MFButAQUUs,1621
+pybinbot-0.0.1.dist-info/licenses/LICENSE,sha256=ECEAqAQ81zTT8PeN7gYqbkZtewkyeleEqQ26MxuHQxs,938
+shared/enums.py,sha256=8rRvUIMq6ApMBBgd_Ef0_8aM6HeYnB37ro5Mh9W6_WY,6624
+shared/logging_config.py,sha256=XZblKXH9KsLUDbIJqFRZPzI0h17-CRBZH4KktVak-TI,1144
+shared/maths.py,sha256=Xcj4_rx9kHjowFhk8ysMNB_FaCcrGcHpK_-0P62xj70,2660
+shared/timestamps.py,sha256=FtZw6hKNJ1N1NUBusW4g5L1PwUZtX98LGFSAxxZFsVw,1587
+shared/types.py,sha256=KfuJzjsbMUHFcBaQ6ZXUbuSyFHbHqehgeY73Zt8lqO8,173
+pybinbot-0.0.1.dist-info/METADATA,sha256=loC9ZtGqe3JanBSuBIn3WNChG4TLcDvcCYr1RrhTLjQ,1220
+pybinbot-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pybinbot-0.0.1.dist-info/top_level.txt,sha256=pm2plP5btgXnaBayjioY_GnmGMW0k3q0j7xXnUsunSY,14
+pybinbot-0.0.1.dist-info/RECORD,,

pybinbot-0.0.1.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.0.1.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.0.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+models
+shared

shared/enums.py

@@ -0,0 +1,266 @@
+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"

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,111 @@
+import math
+import re
+from decimal import Decimal
+from datetime import datetime
+
+
+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 trilling 0s
+    this function will not round the number
+    e.g. 3.140, 3.140000004
+
+    also supress scientific notation
+    e.g. 2.05-5
+    """
+    value = float(value)
+    # supress scientific notation
+    number = float(f"{value:f}")
+    number = float("{0:g}".format(number))
+    return number
+
+
+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
+    e.g. 8e-5 = "0.00008"
+    """
+    dec_num = float(num)
+    num = round_numbers(dec_num, precision)
+    if precision >= 0:
+        decimal_points = precision
+    else:
+        decimal_points = int(Decimal(str(num)).as_tuple().exponent * -1)
+    return f"{num:.{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,66 @@
+from time import time
+import math
+from shared.maths import round_numbers
+from datetime import datetime
+
+
+def timestamp() -> int:
+    ts = time() * 1000
+    rounded_ts = round_timestamp(ts)
+    return rounded_ts
+
+
+def round_timestamp(ts: int | float) -> int:
+    """
+    Round millisecond timestamps to always 13 digits
+    this is the universal format that JS and Python accept
+    """
+    digits = int(math.log10(ts)) + 1
+    if digits > 13:
+        decimals = digits - 13
+        multiplier = 10**decimals
+        return int(round_numbers(ts * multiplier, decimals))
+    else:
+        return int(ts)
+
+
+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, "%Y-%m-%d")
+    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
+    """
+    if len(str(abs(1747852851106))) > 10:
+        # if timestamp is in milliseconds
+        ts = ts // 1000
+    return datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M:%S")

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),
+]