Paper trade a SPY strategy with Gemini CLI

1. Register remote MCP and authenticate in Gemini CLI

Run the shell commands below. --scope user makes the connection available across your CLI projects; use --scope project instead for this project only. This guide is for Gemini CLI, not the Gemini consumer chat app.

Start gemini in the folder where you will save the research files. Inside that session enter /mcp auth nexustrade, finish NexusTrade browser sign-in, then /mcp list. Use /mcp schema to inspect discovered input schemas. These slash commands belong in Gemini CLI, not your shell.

gemini mcp add --transport http --scope user nexustrade https://nexustrade.io/api/mcp
gemini mcp list
gemini

2. Confirm access with an owned-resource read

Ask the client to discover tools and call fetch_portfolios, then pass one returned portfolioId as portfolio_id to get_portfolio. Inspect portfolioId, type, name, isActive and strategies; compare them with the same saved book in NexusTrade. Do not copy IDs from a demonstration. An empty list can be valid for a new account.

A tool-not-found error means revisit discovery. An authorization error means check the selected NexusTrade environment/account and OAuth connection. Do not ask the model to invent a replacement identifier.

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.

3. Create a new candidate and observation record

Daily SPY crossover proposal: buy 10 shares only when the 20-day simple moving average crosses above the 50-day average and no SPY position is held; sell the entire SPY position when the 20-day average crosses below the 50-day average. Use the supported CrossAbove/CrossBelow event indicators, compared with 1, rather than treating every above-average day as a new cross.

Create paper/spy-cli-run-ledger.md with the draft ID, exact configuration, intended $10,000 simulated starting capital, activation date and a review date 30 calendar days later. Those are proposed observation inputs, not recorded performance. Historical testing should be reviewed separately before activation.

Ask Gemini CLI to call build_portfolio with the complete candidate. Inspect valid, canonical portfolio and each issue path, component and message. Fix issues and preview again. After valid is true and you have reviewed the rule, pass the same JSON to create_portfolio and read the saved draft with get_portfolio. Verify type=chat and isActive=false. Keep the generated JSON and returned ID in the record; a portfolio name containing paper does not establish deployment type.

4. Review the paper deployment operation

Show the actual update_portfolio operation before activation: operations contains a deploy entry whose portfolioId is the newly authored chat draft ID. Deploying a chat draft creates a separate paper book. An existing live ID can reactivate brokerage trading, so verify the draft type immediately before the call.

Preview a new candidate with build_portfolio using this rule: Daily SPY crossover proposal: buy 10 shares only when the 20-day simple moving average crosses above the 50-day average and no SPY position is held; sell the entire SPY position when the 20-day average crosses below the 50-day average. Use the supported CrossAbove/CrossBelow event indicators, compared with 1, rather than treating every above-average day as a new cross. Inspect valid, issues and canonical portfolio; fix issues and preview again. When valid and reviewed, pass the same JSON to create_portfolio. Save its full JSON and actual returned ID in paper/spy-cli-run-ledger.md. Use get_portfolio to verify type=chat and isActive=false. Show operations with type deploy and portfolioId equal to that chat ID. Wait for my approval. After activation, find the new deployment with fetch_portfolios and read it with get_portfolio. Stop if type is not paper. Do not deploy an existing live ID.

Create and monitor a separate paper deployment

Deploying an existing live portfolio ID can reactivate real brokerage trading. For this workflow use the newly authored chat candidate and verify the returned deployment is paper. The SDK also separates saved draft IDs from deployment.portfolioId.

No matching rows. Clear the filter to see all records.

5. Verify the running identity and capital

After the approved deployment, use fetch_portfolios to find the new running book and get_portfolio on its returned ID. Confirm type=paper, isActive, strategies, initialValue and the returned deployment settings. Record the actual deployment frequency: Constant and OpenClose are evaluation schedules. A Day backtest interval or a day-based moving-average window does not set the paper evaluation cadence. Compare the capital and rules with the approved record before treating the experiment as started. Keep the chat draft ID and running portfolioId separately.

If several portfolios share a name, use returned IDs and the exact strategies rather than selecting by name alone. A transport timeout does not prove deployment failed. Read the account resources before attempting another deploy; duplicate deployments can create separate experiments.

6. Observe recorded paper history and recover

If the server is missing, check whether you selected user or project scope. Use /mcp reload to rediscover tools after configuration changes. For expired tokens, repeat /mcp auth nexustrade. Shell gemini mcp list can show connection errors. After an interrupted terminal session, reopen the saved run ledger or /resume and continue with the recorded job or deployment ID.

Use query_portfolio_history with the verified running portfolio_id for the observation period. It returns recorded time/value points from the deployed book. get_portfolio_performance returns aggregates, while query_backtest_history reads historical simulations; neither replaces the deployed curve.

If history is empty, check type, activation time, active state and whether observations have been recorded. Do not backtest the same rules and label that curve paper performance. Record actual positions, activity and any rule/cash changes beside the curve. At the review date compare behavior with the frozen plan. When the observation ends, review update_portfolio with operations containing type undeploy and portfolioId equal to the verified running paper ID. After the approved pause, call get_portfolio again and require type=paper and isActive=false. Keep the recorded history; pausing does not require deleting the book.

Pause the verified paper book

Replace the placeholder with the running paper ID you have just read with get_portfolio. Submit this operation only after reviewing that identity and approving the pause. Read the same ID afterward and require type=paper and isActive=false.

{
  "operations": [
    {
      "type": "undeploy",
      "portfolioId": "<verified-running-paper-id>"
    }
  ]
}

Costs and the next task

The local file and proposed rule are planning artifacts. Research and backtest submissions can consume credits; detailed backtest events increase cost. Check your plan and the proposed operation before submitting. OAuth confirms account access, not that a strategy will succeed.

For live deployment, review the separate broker guide, exact trading account and permissions. This client connection does not prove a native brokerage connector or a completed live workflow.

Continue exploring