---
title: "Commands"
description: "Commands enable you to inject external data into your live algorithm as it runs."
canonical: https://www.quantconnect.com/docs/v2/writing-algorithms/live-trading/commands
markdown: https://www.quantconnect.com/docs/v2/writing-algorithms/live-trading/commands.md
language: python
source: https://github.com/QuantConnect/Documentation/tree/master/03%20Writing%20Algorithms/40%20Live%20Trading/41%20Commands
modified: 2026-10-30
index: https://www.quantconnect.com/llms.txt
---

# Commands

[Documentation](https://www.quantconnect.com/docs/v2.md) > [Writing Algorithms](https://www.quantconnect.com/docs/v2/writing-algorithms.md) > [Live Trading](https://www.quantconnect.com/docs/v2/writing-algorithms/live-trading.md) > Commands

> Code examples are shown in Python. Append `?lang=csharp` to this URL for the C# version of this page.

## Introduction

Commands enable you to manually call methods in your live algorithm as it runs. You can command live projects to update your algorithm state, place orders, or run any other logic. Commands are different from [notifications](https://www.quantconnect.com/docs/v2/writing-algorithms/live-trading/notifications.md) because notifications enable you to send information *out* of your algorithm while commands enable you to send information *into* your algorithm.

## Basic Usage

To receive and handle generic commands in your algorithm, define the `on_command` method. This method receives the data you want to inject into your algorithm and returns a boolean that represents if the command was successful.

```python
class BasicCommandAlgorithm(QCAlgorithm):

    def initialize(self):
        self.set_benchmark(lambda x: 1) # So the algorithm needs no asset data.

    def on_command(self, data):
        self.log(f'Got command at {self.time} with data: {data}')
        return True
```

To invoke the `on_command` event handler, send a payload (for example, `{"ticker": "AAPL", "quantity": 1}`) through the [QuantConnect REST API](https://www.quantconnect.com/docs/v2/cloud-platform/api-reference/live-management/live-commands.md) or [LEAN CLI](https://www.quantconnect.com/docs/v2/lean-cli/live-trading/algorithm-control.md). The keys of the payload become the members of the `data` object.

## Encapsulate Event Handlers

To encapsulate the command handler logic, define isolated classes. Command classes should extend the `Command` class. Extensions of the `Command` class must implement a `run` method, which receives the payload you send and returns a boolean that represents if the command was successful. To add the command to your algorithm, call the `add_command` method.

```python
class EncapsulatedCommandAlgorithm(QCAlgorithm):

    def initialize(self):
        MyCommand.ALGORITHM = self
        self.add_command(MyCommand)
        self.set_benchmark(lambda x: 1) # So the algorithm doesn’t need asset data.

    def do_something(self):
        self.log('Something was done!')

class MyCommand(Command):
    ALGORITHM = None
    ticker = None
    quantity = None
    parameters = {}

    def run(self, algorithm):
	    if not MyCommand.ALGORITHM:
            algorithm.log('Please set the static reference to the ALGORITHM attribute in the initialize method: `MyCommand.ALGORITHM = self`')
            return False
        algorithm.log(f"ticker: {self.ticker}; quantity: {self.quantity}; parameters: {self.parameters}")
        MyCommand.ALGORITHM.do_something()
        return True
```

To invoke the `run` method of the class you define, send a payload with a `$type` key (for example, `{"ticker": "AAPL", "quantity": 1, "$type": "MyCommand"}`). The value of the `$type` key must be the `Command` class you define. The other keys of the payload set the members of the class. If you don’t provide a `$type` key, LEAN runs the `on_command` method instead of the `run` method in your custom `Command` class.

To access your algorithm's attributes, you need to create a [global static variable](https://www.quantconnect.com/docs/v2/writing-algorithms/key-concepts/globals-and-statics.md#03-API-Access-by-Global-Static-Variable), and assign the reference to the global variable in the algorithm's `initialize`. Then, in the `run` merhod, you can acess your algorithm's attributes through the global.

## Send Command Link

You can create the command in your algorithm and then send yourself an [email notification](https://www.quantconnect.com/docs/v2/writing-algorithms/live-trading/notifications.md) with a link inside it. When you click the link, it then executes the event handler in your algorithm. To create the link, call the `link` method. The following algorithm demonstrates how send command requests for the `on_command` event handler:

```python
class BasicLinkedCommandAlgorithm(QCAlgorithm):

    def initialize(self):
        self.set_benchmark(lambda x: 1) # So the algorithm needs no asset data.
        link = self.link({"ticker": "AAPL", "quantity": 1})
        self.notify.email("email@address.com", "Run Command?", f"Click here to run: {link}")

    def on_command(self, data):
        self.log(f'Got command at {self.time} with data: {data}')
        return True
```

The following algorithm demonstrates how to send command requests for an event handler you encapsulate in a class:

```python
class EncapsulatedAndLinkedCommandAlgorithm(QCAlgorithm):

    def initialize(self):
        self.add_command(MyCommand)
        self.set_benchmark(lambda x: 1) # So the algorithm doesn’t need asset data.
        potential_command = MyCommand()
        potential_command.ticker = 'AAPL'
        potential_command.quantity = 1
        potential_command.parameters = {"tag": "Signal X"}
        link = self.link(potential_command)
        self.notify.email("email@address.com", "Run Command?", f"Click here to run: {link}")

class MyCommand(Command):
    ticker = None
    quantity = None
    parameters = {}

    def run(self, algorithm):
        algorithm.log(f"ticker: {self.ticker}; quantity: {self.quantity}; parameters: {self.parameters}")
        return True
```

## Broadcast Command

You can create the command in your algorithm and then broadcast it to all live algorithms in your organization, except the source algorithm and commands of unregisted type name. The following algorithm demonstrates how broadcast a command to the `on_command` event handler in all your live algorithms:

```python
class BasicBroadcastCommandAlgorithm(QCAlgorithm):

    def initialize(self):
        self.set_benchmark(lambda x: 1) # So the algorithm needs no asset data.
        link = self.broadcast_command({"ticker": "AAPL", "quantity": 1})

    def on_command(self, data):
        self.log(f'Got command at {self.time} with data: {data}')
        return True
```

You can control the command data by [encapsulating the event handler](https://www.quantconnect.com/docs/v2/writing-algorithms/live-trading/commands.md#03 Encapsulate-Event-Handlers) in a class. The following algorithm demonstrates how to broadcast a command for an event handler you encapsulate in a class:

```python
class EncapsulatedAndBroadcastCommandAlgorithm(QCAlgorithm):

    def initialize(self):
        self.add_command(MyCommand)
        self.set_benchmark(lambda x: 1) # So the algorithm doesn't need asset data.
        potential_command = MyCommand()
        potential_command.ticker = 'AAPL'
        potential_command.quantity = 1
        potential_command.parameters = {"tag": "Signal X"}
        broadcast_result = self.broadcast_command(potential_command)

class MyCommand(Command):
    ticker = None
    quantity = None
    parameters = {}

    def run(self, algorithm):
        algorithm.log(f"ticker: {self.ticker}; quantity: {self.quantity}; parameters: {self.parameters}")
        return True
```

## Send Commands by API

To send a command to your algorithm, send a payload through the [QuantConnect REST API](https://www.quantconnect.com/docs/v2/cloud-platform/api-reference/live-management/live-commands.md) or [LEAN CLI](https://www.quantconnect.com/docs/v2/lean-cli/live-trading/algorithm-control.md). Follow these steps to send a command from the command line. In this case, the script calls the `on_command` method.

1. Install the `requests` library, if you haven't already.
   ```python
   pip install requests
   ```
2. Save the following code as `send_command.py`.
   ```python
   from base64 import b64encode
   from hashlib import sha256
   from time import time
   from sys import argv
   from requests import post

   # Edit these values:
   USER_ID = 0
   API_TOKEN = '_____'
   PROJECT_ID = <project_id>

   BASE_URL = 'https://www.quantconnect.com/api/v2/'

   def get_headers():
       # Get timestamp
       timestamp = f'{int(time())}'
       time_stamped_token = f'{API_TOKEN}:{timestamp}'.encode('utf-8')

       # Get hased API token
       hashed_token = sha256(time_stamped_token).hexdigest()
       authentication = f'{USER_ID}:{hashed_token}'.encode('utf-8')
       authentication = b64encode(authentication).decode('ascii')

       # Create headers dictionary.
       return {
           'Authorization': f'Basic {authentication}',
           'Timestamp': timestamp
       }

   def create_command(project_id, command):
       return post(
           f'{BASE_URL}/live/commands/create',
           headers=get_headers(),
           json={"projectId": project_id, "command": command}
       ).json()

   # Read the ticker, quantity, and (optional) command type from the command line:
   ticker = argv[1]
   quantity = int(argv[2])
   command = {'ticker': ticker, 'quantity': quantity}
   if len(argv) > 3:
       command['$type'] = argv[3]
   print(create_command(PROJECT_ID, command))
   ```
3. Replace the placeholder values at the top of the file with your user Id, API token, and project Id.
4. Run the script, passing the ticker and quantity as arguments. The first form below calls the `on_command` method; the second adds an optional third argument that sets the `$type` key to route to an encapsulated `Command` subclass handler.
   ```python
   python send_command.py AAPL 1
   python send_command.py AAPL 1 MyCommand
   ```

To get your user Id and API token, see [Request API Token](https://www.quantconnect.com/docs/v2/cloud-platform/community/profile.md#09-Request-API-Token).

## Broadcast Commands by API

To broadcast a command to your live algorithms, send a payload through the [QuantConnect REST API](https://www.quantconnect.com/docs/v2/cloud-platform/api-reference/live-management/live-commands.md) or [LEAN CLI](https://www.quantconnect.com/docs/v2/lean-cli/live-trading/algorithm-control.md). Follow these steps to broadcast a command to all projects in your organization from the command line.

1. Install the `requests` library, if you haven't already.
   ```python
   pip install requests
   ```
2. Save the following code as `broadcast_command.py`.
   ```python
   from base64 import b64encode
   from hashlib import sha256
   from time import time
   from sys import argv
   from requests import post

   # Edit these values:
   USER_ID = 0
   API_TOKEN = '_____'
   ORGANIZATION_ID = '_____'

   BASE_URL = 'https://www.quantconnect.com/api/v2/'

   def get_headers():
       # Get timestamp
       timestamp = f'{int(time())}'
       time_stamped_token = f'{API_TOKEN}:{timestamp}'.encode('utf-8')

       # Get hased API token
       hashed_token = sha256(time_stamped_token).hexdigest()
       authentication = f'{USER_ID}:{hashed_token}'.encode('utf-8')
       authentication = b64encode(authentication).decode('ascii')

       # Create headers dictionary.
       return {
           'Authorization': f'Basic {authentication}',
           'Timestamp': timestamp
       }

   def broadcast_command(command):
       return post(
           f'{BASE_URL}/live/commands/broadcast',
           headers=get_headers(),
           json={"organizationId": ORGANIZATION_ID, "command": command}
       ).json()

   # Read the ticker, quantity, and (optional) command type from the command line:
   ticker = argv[1]
   quantity = int(argv[2])
   command = {'ticker': ticker, 'quantity': quantity}
   if len(argv) > 3:
       command['$type'] = argv[3]
   print(broadcast_command(command))
   ```
3. Replace the placeholder values at the top of the file with your user Id, API token, and organization Id.
4. Run the script, passing the ticker and quantity as arguments. The first form below calls the `on_command` method; the second adds an optional third argument that sets the `$type` key to route to an encapsulated `Command` subclass handler.
   ```python
   python broadcast_command.py AAPL 1
   python broadcast_command.py AAPL 1 MyCommand
   ```

To get your user Id, API token, and organization Id, see [Request API Token](https://www.quantconnect.com/docs/v2/cloud-platform/community/profile.md#09-Request-API-Token) and [Get Organization Id](https://www.quantconnect.com/docs/v2/cloud-platform/organizations/getting-started.md#05-Get-Organization-Id).

## Examples

The following examples demonstrate common practices for implementing live commands.

### Example 1: Grey Box

The following algorithm trades a simple EMA cross strategy on SPY. However, instead of direct ordering by the algorithm as a "black box", it sends an email to ask for clicking a confirmation link before ordering, making each order decision an informed manual decision. The algorithm is called a "grey box".

```python
class LiveCommandAlgorithm(QCAlgorithm):
    def initialize(self) -> None:
        self.set_start_date(2024, 9, 12)
        self.set_end_date(2024, 10, 1)
        self.set_cash(1000000)

        # Request SPY data to trade.
        self.spy = self.add_equity("SPY").symbol
        # Create an EMA indicator to generate trade signals.
        self._ema = self.ema(self.spy, 20, Resolution.DAILY)
        # Warm-up indicator for immediate readiness.
        self.warm_up_indicator(self.spy, self._ema, Resolution.DAILY)

    def on_data(self, slice: Slice) -> None:
        bar = slice.bars.get(self.spy)
        if bar and self.live_mode:
            # Trend-following strategy using price and EMA.
            # If the price is above EMA, SPY is in an uptrend, and we buy it.
            # We sent a link to our email address and await confirmation.
            if bar.close > self._ema.current.value and not self.portfolio[self.spy].is_long:
                link = self.link({"ticker": "SPY", "size": 1})
                self.notify.email("email@address.com", "Trade Confirmation Needed", f"Click here to run: {link}")
            elif bar.close < self._ema.current.value and not self.portfolio[self.spy].is_short:
                link = self.link({"ticker": "SPY", "size": -1})
                self.notify.email("email@address.com", "Trade Confirmation Needed", f"Click here to run: {link}")

    def on_command(self, data: DynamicData) -> Optional[bool]:
        # The algorithm will place the order if we click the email link to confirm the trade.
        self.set_holdings(data["ticker"], data["size"])
        return True
```

### Example 2: Parent-Child Communication

**Parent algorithm**

The parent algorithm is connected to a brokerage. It receives commands from other algorithms and places market orders based on those commands.

```python
class ParentAlgorithm(QCAlgorithm):

    def initialize(self):
        self.set_start_date(2024, 9, 1)
        self.set_end_date(2024, 12, 31)
        self.set_cash(100_000)

        # Remove benchmark so doesn't need asset data.
        self.set_benchmark(lambda x: 1)

        # Seed each asset with it's price to trade right away.
        self.settings.seed_initial_prices = True

    def on_command(self, payload):
        self.log(f'{self.time} - Execute on_command(): {payload}')
        equity = self.add_equity(payload.ticker)

        if payload.email:
            self.notify.email(address=payload.email, subject=f"Order Executed from {payload.source}", message=f"{equity.symbol}, {payload.quantity}, {payload.source}")

        self.market_order(equity.symbol, payload.quantity, asynchronous=True, tag=payload.source)
        return True
```

**Child algorithm**

The child algorithm is connected to a paper trading account. It contains the trading logic and sends commands to the parent algorithm for execution.

```python
class ChildAlgorithm (QCAlgorithm):
    def initialize(self):
        # Set the initials to identify the sender and the cash this algorithm will use.
        self._initials = 'C1'
        self.set_start_date(2024, 9, 1)
        self.set_end_date(2024, 12, 31)
        self.set_cash(10_000)

    def on_order_event(self, order_event: OrderEvent):
        # When an order is filled, we send a command to the parent algorithm with the order details.
        if order_event.status == OrderStatus.FILLED:
            self.log(f'{self.time} - Sending command')
            response = send(self, order_event.symbol.value, order_event.fill_quantity, self._initials)
            self.log(f'{self.time} - Command response {response}')

def send(algorithm, ticker, quantity, name):
    if not algorithm.live_mode:
        return ''
    # Set the project ID with the ID of your parent algorithm.
    algorithm.project_id = 30123456
    # Generate the command link with the desired data payload, and execute with download_data.
    link = algorithm.link({'ticker': ticker, 'quantity': quantity, 'name': name})
    return Extensions.download_data(link)
```

### Other Examples

For more examples, see the following algorithms:

**Demonstration Algorithm**

- [CallbackCommandRegressionAlgorithm.py](https://github.com/QuantConnect/Lean/blob/master/Algorithm.Python/CallbackCommandRegressionAlgorithm.py) (Python)