stockapis-bot 0.3.2

Trading Bot SDK for StockAPIs - Build custom trading bots with ease

stockapis-bot

Python SDK for building trading bots with StockAPIs platform.

Features

• Pydantic v2 typed settings with JSON Schema (auto-sent to Django)
• Deterministic bot_id from name (UUID5 - same name = same ID everywhere)
• Built-in environment configs (DEV/PROD) - no infrastructure setup needed
• gRPC streaming for real-time signals from Django
• Binance Futures testnet/live trading
• Redis pub/sub for event handling
• Telegram channel signal extraction

Install

pip install stockapis-bot

Environment

Only credentials needed - infrastructure config (hosts, ports) is built into the package:

# Binance TESTNET
BINANCE__API_KEY=your_testnet_api_key
BINANCE__API_SECRET=your_testnet_api_secret
BINANCE__TESTNET=true

# gRPC API Key (host/port built-in per environment)
GRPC__API_KEY=your-api-key

# Redis (host/port built-in per environment)
REDIS__PASSWORD=
REDIS__CHANNEL=trading_signals

# Telegram Spy (optional)
TELEGRAM__API_ID=123456
TELEGRAM__API_HASH=your_api_hash
TELEGRAM__SESSION=1BQA...          # from `telegram-spy auth`
TELEGRAM__CHANNELS=channel1,channel2

Quick Start

from decimal import Decimal
from pydantic import Field
from stockapis_bot import (
    BotClient, BotSettings, ClientConfig, Environment,
    TradingBot, TradingSignal, SignalDecision,
)

# 1. Define settings schema (sent to Django for dynamic form generation)
class ScalperSettings(BotSettings):
    min_confidence: float = Field(default=0.7, ge=0, le=1, description="Min confidence")
    position_size: Decimal = Field(default=Decimal("100"), description="Position USDT")

# 2. Create bot with settings schema
class MyBot(TradingBot):
    settings_schema = ScalperSettings  # Schema sent to Django on registration

    async def on_signal(self, signal: TradingSignal) -> SignalDecision:
        # Access typed settings (updated from Django)
        if signal.confidence < self.settings.min_confidence:
            return SignalDecision.skip("Low confidence")

        qty = str(self.settings.position_size)
        if signal.is_buy_signal:
            return SignalDecision.buy(qty, "High confidence buy")
        elif signal.is_sell_signal:
            return SignalDecision.sell(qty, "High confidence sell")

        return SignalDecision.skip("Unknown signal")

    async def on_start(self) -> None:
        print(f"Bot {self.name} ({self.bot_id}) started")
        print(f"Settings: {self.settings}")

    async def on_stop(self, reason: str) -> None:
        print(f"Bot stopped: {reason}")

# 3. Run - bot_id auto-generated from name (deterministic UUID5)
async def main():
    bot = MyBot(name="my-scalper")
    config = ClientConfig.from_settings(
        bot_id=bot.bot_id,
        bot_name=bot.name,
        env=Environment.DEV,    # or Environment.PROD
        include_exchange=True,  # Binance from .env
        include_redis=True,     # Redis listener
    )
    client = BotClient.create(bot, config)  # Schema sent to Django here
    await client.run()

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Environments

Built-in infrastructure configs - just select DEV or PROD:

# Development (localhost)
config = ClientConfig.from_settings(bot_id, bot_name, env=Environment.DEV)

# Production (StockAPIs cloud)
config = ClientConfig.from_settings(bot_id, bot_name, env=Environment.PROD)

Bot Methods

# Trading
await self.buy(symbol, quantity)
await self.sell(symbol, quantity, reduce_only=True)

# Market data
ticker = await self.get_ticker("BTCUSDT")  # ticker.price
balance = await self.get_balance()          # balance.available_usdt

# Utils
qty = await self.calculate_quantity(symbol, usdt_amount=100, leverage=10)
await self.set_leverage(symbol, leverage=20)

# State
self.is_running    # bool
self.is_active     # bool (running + config.active)
self.config        # BotConfig from Django (enabled, active, etc.)
self.settings      # Typed settings (ScalperSettings) - updated from Django

CLI

Command	Description	Args
telegram-spy auth	Generate session string	-i API_ID -h API_HASH
telegram-spy test	Test session validity	-i API_ID -h API_HASH -s SESSION
telegram-spy channels	List your channels	-i API_ID -h API_HASH -s SESSION
telegram-spy run	Run spy → Redis	reads from env
telegram-spy send	Send test signal	BOT__TOKEN env

License

MIT