stockapis-bot 0.3.0

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

stockapis-bot

Python SDK for building trading bots with StockAPIs platform.

Features

• 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

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

# Django gRPC
GRPC__HOST=localhost
GRPC__PORT=50051
GRPC__API_KEY=dev-key

# Redis
REDIS__HOST=localhost
REDIS__PORT=6379
REDIS__CHANNEL=trading_signals

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

Quick Start

from stockapis_bot import BotClient, ClientConfig, TradingBot, TradingSignal, SignalDecision

class MyBot(TradingBot):

    async def on_signal(self, signal: TradingSignal) -> SignalDecision:
        """Main handler - called for each signal."""
        if signal.confidence < 0.7:
            return SignalDecision.skip("Low confidence")

        # Calculate quantity from USDT amount
        qty = await self.calculate_quantity(signal.symbol, usdt_amount=100, leverage=10)

        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")

    # Lifecycle hooks
    async def on_start(self) -> None:
        print(f"Bot {self.name} started")

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

    async def on_config_update(self, config) -> None:
        print(f"Config updated: active={config.active}")

# Run
BOT_ID = "550e8400-e29b-41d4-a716-446655440000"  # UUID from Django
bot = MyBot(bot_id=BOT_ID, name="My Bot")
config = ClientConfig.from_settings(bot_id=BOT_ID, bot_name="My Bot")
client = BotClient.create(bot, config)
await client.run()

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

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