Backtest a portfolio in Python

TL;DR

Build the saved portfolio rules, submit one backtest and wait on its returned operation rather than creating duplicate jobs. Preserve the request key for identical retries and inspect completed statistics, orders and fees. The worked seven stock AI template returned 70.97% in 2024 versus SPY's 25.30%, with 23.49% maximum drawdown versus 9.13%. That receipt came from the product's QuickTest, not execution of your local SDK script; save your chosen fees and dividend policy for a new comparison.

A completed example from the product

The Artificial Intelligence Revolution template completed a QuickTest on October 10, 2026, for January 1 through December 31, 2024, with $10,000 starting capital. The first chart point was January 2. The statistics table reported 70.97% for the template and 25.30% for Hold SPY, with ending value $17,096.90.

The table return uses the $10,000 initial value; the chart's 71.14% badge uses its first visible point. Follow the purchases into the seven ending positions and inspect the trades around the largest drawdown. The SDK example below creates the same fixed basket. Save your selected fees and dividend policy with a new run to compare its result with this product example.

Install and authenticate

These examples use NexusTrade Python SDK 1.42.0. Use a registered API key with write and read access for submission and result retrieval.

python3 -m pip install nexustrade==1.42.0
printf 'NexusTrade API key: '
read -rs NEXUSTRADE_API_KEY
export NEXUSTRADE_API_KEY
printf '\n'

Create a portfolio and submit the backtest

Save this Python example in a script and run it in the environment where you installed nexustrade and configured the API key. It builds the template's seven Always-buy rules with percent-of-buying-power sizing, then submits a 2024 SPY comparison and waits for completion. Each rule can buy again when evaluated; the template has no sell rule. Follow the resulting orders to see how each purchase uses remaining buying power.

from nexustrade import NexusTradeClient, Value, backtest, buy, portfolio, strategy

# Same fixed seven-stock buying-power recipe tested in the product UI.
universe = [("CRM", 5), ("AVGO", 5), ("META", 15), ("TSLA", 15),
            ("NVDA", 20), ("MSFT", 20), ("GOOGL", 20)]
book = portfolio("AI template worked example", [
    strategy("Buy " + symbol, Value(1) == Value(1),
             buy(symbol, percent, "percent of buying power"))
    for symbol, percent in universe
], initial_value=10000)

# Local authoring above makes no request. The following submits one job.
client = NexusTradeClient()
operation = client.create_backtest(
    backtest(book, start_date="2024-01-01", end_date="2024-12-31", interval="Day", baseline_symbol="SPY"),
    idempotency_key="seo-ai-template-2024-v1",
)
result = client.wait_for_backtest(operation["id"])
print(result["result"])

Wait for the result

create_backtest returns an operation immediately. wait_for_backtest polls that operation rather than submitting a second job. Preserve the idempotency key while retrying the same request. Changing the payload requires a new key.

Successful completion returns the operation's result. The wait helper raises on failed or cancelled operations by default. If waiting times out, retrieve the operation with client.get_backtest using the saved ID or resume waiting on that ID. Inspect the completed statistics and chart, then follow the signals, filled orders and fee entries to understand the result.

Follow one worked path

Step 1 of 3

Install the shown SDK version

These examples use NexusTrade Python SDK 1.42.0. Use a registered API key with write and read access for submission and result retrieval.

What you should see

The matching package is available and the request uses the appropriate read, write or lake scope.

Shell

Copy command

python3 -m pip install nexustrade==1.42.0
printf 'NexusTrade API key: '
read -rs NEXUSTRADE_API_KEY
export NEXUSTRADE_API_KEY
printf '\n'

Step 2 of 3

Review the full candidate

Run the complete seven-rule example below after reviewing its sequential percent-of-buying-power sizing, dates and capital.

What you should see

The saved candidate is separate from the historical backtest job. Submission can consume credits; do not run again while the original job is pending.

Python

Copy Python example

from nexustrade import NexusTradeClient, Value, backtest, buy, portfolio, strategy

# Same fixed seven-stock buying-power recipe tested in the product UI.
universe = [("CRM", 5), ("AVGO", 5), ("META", 15), ("TSLA", 15),
            ("NVDA", 20), ("MSFT", 20), ("GOOGL", 20)]
book = portfolio("AI template worked example", [
    strategy("Buy " + symbol, Value(1) == Value(1),
             buy(symbol, percent, "percent of buying power"))
    for symbol, percent in universe
], initial_value=10000)

# Local authoring above makes no request. The following submits one job.
client = NexusTradeClient()
operation = client.create_backtest(
    backtest(book, start_date="2024-01-01", end_date="2024-12-31", interval="Day", baseline_symbol="SPY"),
    idempotency_key="seo-ai-template-2024-v1",
)
result = client.wait_for_backtest(operation["id"])
print(result["result"])

Step 3 of 3

Create a portfolio and submit the backtest

Save this Python example in a script and run it in the environment where you installed nexustrade and configured the API key. It builds the template's seven Always-buy rules with percent-of-buying-power sizing, then submits a 2024 SPY comparison and waits for completion. Each rule can buy again when evaluated; the template has no sell rule. Follow the resulting orders to see how each purchase uses remaining buying power.

Return from starting capital

AI template: 70.97% · Hold SPY: 25.30%

Sharpe ratio

AI template: 1.75 · Hold SPY: 1.42

Sortino ratio

AI template: 2.38 · Hold SPY: 1.90

Maximum drawdown

AI template: 23.49% · Hold SPY: 9.13%

What you should see

The shown product receipt demonstrates its originating workflow, not proof that your local SDK request has executed.

Continue exploring