Fractrade Agent

Agents are the core components of the Fractrade platform. They are responsible for executing trading strategies and generating trading actions.

Agent Types

Fractrade supports two types of agents:

Execution Agents

Execution Agents have an associated execution wallet and automatically execute trades on your behalf. When an Execution Agent generates an action, the platform will:

  1. Create the action in the database
  2. Publish the action to the websocket
  3. Execute the action using the agent's execution wallet

Execution Agents are ideal for fully automated trading strategies where you want trades to be executed without manual intervention.

Server Execution

When an agent is configured with an execution wallet, it can execute trades in two ways:

  1. Server Execution (server_execution=true): The trade is executed by the server using the agent's execution wallet
  2. Client Execution (server_execution=false): The trade is executed by the ExecutionClient running on your machine

This flexibility allows you to: - Run strategies fully on the server - Execute trades from your own infrastructure - Implement custom execution logic - Maintain control over your private keys

Creating an Agent

To create an agent, you need to:

  1. Define your agent's configuration
  2. Implement your agent's logic
  3. Deploy your agent to the Fractrade platform

Agent Configuration

The agent configuration defines the agent's parameters and settings. Here's an example configuration:

{
  "name": "Simple Moving Average Crossover",
  "description": "A simple moving average crossover strategy",
  "version": "1.0.0",
  "config": {
    "fast_period": 10,
    "slow_period": 20,
    "symbol": "BTC",
    "size": 0.01,
    "leverage": 10
  }
}

Agent Logic

The agent logic is implemented in Python. Here's an example of a simple moving average crossover strategy:

from fractrade import Agent
from fractrade.actions import ActionType

class SimpleMovingAverageCrossover(Agent):
    def __init__(self, config):
        super().__init__(config)
        self.fast_period = config['fast_period']
        self.slow_period = config['slow_period']
        self.symbol = config['symbol']
        self.size = config['size']
        self.leverage = config['leverage']

    def process_event(self, event):
        # Skip non-fill events
        if event.event_type != 'hyperliquid_fill':
            return []

        # Extract data from event
        fill_data = event.data
        symbol = fill_data.get('coin')
        executed_size = float(fill_data.get('sz'))
        execution_price = float(fill_data.get('px'))

        # Create trade action
        action = {
            'action_id': ActionType.EXECUTE_HYPERLIQUID_PERP_TRADE,
            'config': {
                'position': {
                    'symbol': symbol,
                    'size': str(executed_size),
                    'side': 'BUY',
                    'reduce_only': False
                },
                'metadata': {
                    'event_id': str(event.id),
                    'price': execution_price,
                    'leverage': self.leverage,
                    'server_execution': True  # Execute on server
                }
            }
        }

        return [action]

Deploying an Agent

To deploy an agent, you need to:

  1. Package your agent code
  2. Upload it to the Fractrade platform
  3. Configure your agent

Packaging Your Agent

Your agent code should be packaged as a Python module. The module should contain:

  • A main agent class that inherits from fractrade.Agent
  • Any dependencies required by your agent

Uploading Your Agent

You can upload your agent using the Fractrade CLI:

fractrade agent upload --path ./my-agent

Configuring Your Agent

After uploading your agent, you need to configure it:

  1. Set the agent configuration
  2. Set up the execution wallet (optional)
  3. Configure server execution settings

Agent Actions

Agents generate actions in response to events. The supported action types are:

  1. EXECUTE_HYPERLIQUID_PERP_TRADE: Execute perpetual trades
  2. SET_HYPERLIQUID_PERP_STOP_LOSS: Set stop loss orders
  3. SET_HYPERLIQUID_PERP_TAKE_PROFIT: Set take profit orders

Actions are created using the create_action method:

self.create_action(
    action_type=ActionType.EXECUTE_HYPERLIQUID_PERP_TRADE,
    config={
        'position': {
            'symbol': 'BTC',
            'size': '0.01',
            'side': 'BUY',
            'reduce_only': False
        },
        'metadata': {
            'price': 50000.0,
            'leverage': 10,
            'server_execution': True
        }
    }
)

Agent Monitoring

You can monitor your agents using the Fractrade dashboard. The dashboard shows:

  • Agent status
  • Agent performance
  • Agent logs
  • Agent actions

Agent WebSocket

Each agent has a dedicated WebSocket endpoint that broadcasts its trading actions. You can connect to this endpoint using the ExecutionClient to execute trades locally on your machine.