Fractrade ExecutionClient

The ExecutionClient is a Python client that executes trading actions received via WebSocket from the Fractrade platform.

Overview

The Fractrade platform (fractrade.xyz) allows you to create trading agents that generate trading actions. Each agent has a dedicated WebSocket connection that broadcasts these actions. The ExecutionClient connects to this WebSocket and executes the trading actions locally on your machine.

Action Types

The client handles the following action types:

1. EXECUTE_HYPERLIQUID_PERP_TRADE: Execute perpetual trades (open/close positions)
2. SET_HYPERLIQUID_PERP_STOP_LOSS: Set stop loss orders
3. SET_HYPERLIQUID_PERP_TAKE_PROFIT: Set take profit orders

Installation

pip install fractrade-executor

Configuration

The executor requires the following environment variables:

# Required
FRAC_WS_URL=wss://your-websocket-url
FRAC_USER_TOKEN=your-user-token
HYPERLIQUID_PRIVATE_KEY=your-private-key
HYPERLIQUID_PUBLIC_ADDRESS=your-wallet-address

# Optional
LOGLEVEL=INFO  # Set to DEBUG for more detailed logs

Basic Usage

from fractrade_executor.executor import FractradeExecutor

async def main():
    # Create and start the executor
    executor = FractradeExecutor()

    try:
        await executor.start()
        print("Executor running. Press Ctrl+C to stop.")

        # Wait for shutdown event
        await executor._shutdown_event.wait()

    except KeyboardInterrupt:
        print("Shutting down...")
    finally:
        await executor.stop()

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

Advanced Usage

You can customize the executor by subclassing FractradeExecutor and overriding its methods:

class CustomExecutor(FractradeExecutor):
    async def handle_hyperliquid_perp_trade(self, config):
        """Custom trade handling logic"""
        self.logger.info("Processing trade: %s", config)
        return await super().handle_hyperliquid_perp_trade(config)

    async def handle_set_hyperliquid_perp_stop_loss(self, config):
        """Custom stop loss handling logic"""
        self.logger.info("Setting stop loss: %s", config)
        return await super().handle_set_hyperliquid_perp_stop_loss(config)

    async def handle_set_hyperliquid_perp_take_profit(self, config):
        """Custom take profit handling logic"""
        self.logger.info("Setting take profit: %s", config)
        return await super().handle_set_hyperliquid_perp_take_profit(config)

WebSocket Messages

The executor receives WebSocket messages in the following format:

{
    "type": "ACTION",
    "data": {
        "action_id": "execute_hyperliquid_perp_trade",
        "config": {
            "position": {
                "symbol": "BTC",
                "size": "0.01",
                "side": "BUY",
                "reduce_only": false
            },
            "metadata": {
                "event_id": "...",
                "price": 50000.0,
                "leverage": 10
            }
        }
    }
}

Error Handling

The executor includes comprehensive error handling and logging:

• Connection errors are automatically retried
• Trade execution errors are logged with details
• Invalid messages are logged and skipped
• Graceful shutdown on interruption

Logging

The executor uses Python's standard logging module. Set the LOGLEVEL environment variable to control log output:

LOGLEVEL=DEBUG  # For detailed debugging
LOGLEVEL=INFO   # For normal operation
LOGLEVEL=WARNING  # For minimal output