Backtest trading strategies with Codex

TL;DR

Codex can validate a saved strategy, create an inactive draft and run a historical comparison through NexusTrade. The five dividend grower simulation returned 44.80% versus SPY's 33.99% from January 2025 through October 7, 2026, but 340.90% versus 419.23% from January 2014. Candidate transactions cost 0.1%; the displayed SPY benchmark pays no candidate commissions. After an interruption, continue the accepted test rather than submit another.

Explore the completed 2025 through 2026 test

Strategy return

44.80%

SPY return

33.99%

Maximum drawdown

24.33%

Strategy fees

$24.15

Recorded historical simulation: Jan 02, 2025 to Oct 07, 2026. Initial capital was $10,000.

Recorded in NexusTrade on October 8, 2026. Strategy assumptions: fractional shares, reinvested dividends and a 0.1% stock transaction fee. The stored SPY benchmark pays no candidate commissions.

Connect Codex in this workspace

codex mcp add nexustrade --url https://nexustrade.io/api/mcp
codex mcp login nexustrade

Run these commands in the project folder where you will use Codex. Complete NexusTrade OAuth, start Codex and use /mcp to inspect the connection.

Try this example in Codex

Connect Codex, then copy the request below. Review the returned result before continuing.

The rules behind this result

Allocation trigger

Review allocations when portfolio value equals its initial value OR at least 30 days have passed since a filled buy. This is not an exact monthly schedule.

Equal weights

Each selected company has the same weight: five qualifying companies would target 20% each before execution effects.

Execution assumptions

Fractional shares and reinvested dividends; the original stock fee was 0.1% per transaction.

From the S&P 500 universe, keep companies meeting the ten-year annual dividend-increase filter, select the five largest by market value and weight them equally. The target is 100% invested.

Create and read back the exact strategy

Use the reviewed configuration at https://nexustrade-prod.nyc3.cdn.digitaloceanspaces.com/Explore/Data/existing-dividend-five-configuration-20261010-2468740bdaf783a8.json. Ask your client to pass that complete object to build_portfolio, inspect valid and issues, then show the canonical portfolio. After reviewing it, save the same JSON with create_portfolio and read the returned chat draft with get_portfolio. Keep the draft ID in your experiment record.

Check the SP500 universe, dividend filter, market-cap ranking, five selected names, equal weights, full deployment, 30-day trigger, fractional shares and reinvestment against the reviewed configuration. Keep the new draft undeployed while testing.

Reproduce the five-dividend-growers experiment in Codex. Read the exact configuration at https://nexustrade-prod.nyc3.cdn.digitaloceanspaces.com/Explore/Data/existing-dividend-five-configuration-20261010-2468740bdaf783a8.json. Pass the complete configuration to build_portfolio. Show valid, issues and canonical rules. Preserve the universe, filter, ranking, weighting, rebalance trigger, fractional shares and dividend policy. After I approve the rules, save the same JSON with create_portfolio, then read the returned portfolio_id with get_portfolio. Record that chat draft ID. Stop before backtesting or deployment.

Submit the matching historical test

Continue only when the connected client has the required authoring and backtest tools. Review the dates, capital, fee and dividend assumptions, and research-token cost before approving one test.

Replace the placeholder with the returned chat draft ID. Review these inputs, then approve one backtest_portfolio call. They match the displayed 2025 run. Save the accepted backtest ID before leaving the conversation.

generate_events is false for the curve comparison. Enable it when you want to inspect individual signals and orders; detailed event capture uses more credits. Keep all other settings fixed when making that inspection run.

{
  "portfolio_id": "REPLACE_WITH_RETURNED_CHAT_ID",
  "start_date": "2025-01-02",
  "end_date": "2026-10-07",
  "interval": "Day",
  "initial_value": 10000,
  "baseline_symbol": "SPY",
  "generate_events": false,
  "dividend_policy": "reinvest",
  "fee_config": {
    "Stock": {
      "amount": 0.1,
      "type": "percent"
    }
  }
}

Tool reference

Inspect the completed curve and explain a rebalance

Poll query_backtest_status with the accepted backtest_id. PENDING or RUNNING means continue with that same ID. Resolve a reported ERROR before changing the experiment. Once complete, read query_backtest_history and follow pagination for the full period. Save the completed statistics and history with the rules and inputs.

Compare value with comparisonValue, then follow cash and positionValue around a rebalance or drawdown. With detailed events enabled, ask the client to read query_backtest_events and explain which condition fired, which stocks qualified, how weights changed and which orders filled. Keep the explanation tied to returned records.

1. Detailed signal traces

   The original example used generate_events:false. A new generate_events:true test costs 5× research tokens; review that request before submitting it and read query_backtest_events while its three-day traces are retained.

Use the accepted backtest_id to poll query_backtest_status until complete. Then read query_backtest_history with that same ID, page 1 and page_size 500; follow all pages. Show the strategy and SPY curves, return, maximum drawdown and fees for 2025-01-02 through 2026-10-07. Explain one rebalance or drawdown using cash, holdings and recorded order events when available. Preserve the returned IDs and source fields in the experiment record. Keep polling the existing test rather than submitting another.

Compare the other recorded periods

The same rules also have completed runs starting in 2022 and 2014. Compare the full period table before selecting a variant; the long 2014 run returned less than SPY.

Inspect the longer recorded period

Connect Codex in the workspace you will use

codex mcp add nexustrade --url https://nexustrade.io/api/mcp
codex mcp login nexustrade
codex mcp list

Confirm access with an owned-resource read

Use only NexusTrade read tools. Call fetch_portfolios, then pass one returned portfolioId as the portfolio_id input to get_portfolio. Show portfolioId, type, name, isActive and complete strategies. Do not create, edit, backtest, deploy or place orders.

Create one variant, then test unseen dates

Save a separate variant that changes only SelectTop.limit from five to ten. Keep the universe, dividend filter, weights, capital, fees, interval and development dates fixed. Record both configurations and their completed backtest IDs before comparing return, drawdown, holdings and turnover.

After choosing a candidate, freeze its configuration and decision criteria. The three displayed historical periods have already been inspected. Select another chronological period you have not used in the example, corpus search or variant selection, then evaluate the frozen candidate once. Keep further revisions in a new research cycle. An optional final lockbox follows the same rule.

Reconnect Codex and continue the recorded test

Keep the recorded experiment

Save the exact configuration, draft ID, accepted backtest ID, inputs and completed result together. Reopen that record after a connection interruption and continue polling the accepted run. Before paper trading, review a separate paper draft and observe its actual deployed history.

Exact strategy configuration

{
  "initialValue": 10000,
  "supportsFractionalShares": true,
  "dividendPolicy": "reinvest",
  "strategies": [
    {
      "active": true,
      "condition": {
        "lhs": null,
        "rhs": null,
        "comparison": null,
        "type": "Or",
        "conditions": [
          {
            "lhs": {
              "compound": false,
              "targetAssets": [],
              "type": "PortfolioValue"
            },
            "rhs": {
              "compound": false,
              "targetAssets": [],
              "type": "InitialValue"
            },
            "comparison": "equal",
            "type": "Base"
          },
          {
            "lhs": {
              "compound": false,
              "targetAssets": [],
              "side": "Buy",
              "type": "DaysSinceOrder",
              "orderStatus": "Filled"
            },
            "rhs": {
              "compound": false,
              "targetAssets": [],
              "value": 30,
              "type": "Value"
            },
            "comparison": "greaterThanOrEqual",
            "type": "Base"
          }
        ]
      },
      "action": {
        "type": "DynamicRebalance",
        "universe": {
          "source": "SP500"
        },
        "pipeline": [
          {
            "type": "Filter",
            "condition": {
              "lhs": {
                "compound": true,
                "targetAssets": [],
                "type": "ConsecutiveIncrease",
                "maxLength": 1,
                "period": "Year",
                "lookback": 10,
                "indicators": [
                  {
                    "compound": false,
                    "targetAsset": {
                      "type": "",
                      "symbol": ""
                    },
                    "targetAssets": [],
                    "type": "LastDividend"
                  }
                ]
              },
              "rhs": {
                "compound": false,
                "targetAssets": [],
                "value": 10,
                "type": "Value"
              },
              "comparison": "greaterThanOrEqual",
              "type": "Base"
            }
          },
          {
            "type": "SelectTop",
            "metric": {
              "compound": false,
              "targetAsset": {
                "type": "",
                "symbol": ""
              },
              "targetAssets": [],
              "type": "Fundamental",
              "metric": "marketCap"
            },
            "limit": 5,
            "direction": "Highest"
          }
        ],
        "weightIndicator": {
          "compound": false,
          "targetAssets": [],
          "value": 1,
          "type": "Value"
        },
        "deploymentPercent": {
          "compound": false,
          "targetAssets": [],
          "value": 100,
          "type": "Value"
        }
      },
      "orderExecution": {
        "type": "Market"
      },
      "automaticOrderApproval": false
    }
  ],
  "name": "Five largest dividend growers",
  "cash": 10000,
  "buyingPower": 10000,
  "supportsCrypto": false,
  "alertsEnabled": false
}

Chart range diagnostics

Continue after a Codex connection or test interruption

1. NexusTrade or a tool is missing

   Use /mcp in the active task. Authenticate in the app or run codex mcp login nexustrade in the CLI. Restart the desktop server entry after editing it. Confirm build_portfolio, create_portfolio, backtest_portfolio, query_backtest_status and query_backtest_history are available before starting this workflow.

2. An ID is rejected

   Use the portfolio_id or backtest_id returned to your own connected account. A demonstration ID or redacted receipt is not an identifier for your new test.

3. The test is PENDING or RUNNING

   Poll query_backtest_status with the same accepted backtest_id. Continue the accepted operation after reconnecting rather than submitting another test.

4. The test reports ERROR

   Retain the returned error and exact request. Resolve that cause before changing the experiment or approving another submission.

5. History or detailed events are unavailable

   Backtest history is retained for 30 days. Detailed events require generate_events:true and are retained for three days. Save the completed result when it returns; enabling events costs 5× research tokens.

Continue exploring