Skip to content

Development

git clone https://github.com/brownjosiah/fidelity-trader-api.git
cd fidelity-trader-api
pip install -e ".[dev,cli,service]"

# Run tests
pytest                              # all 1687 tests
pytest tests/test_positions.py -v   # single module
pytest --cov=fidelity_trader        # with coverage

# Lint
ruff check src/ service/ tests/

Adding New API Modules

This SDK is built from captured network traffic. The workflow:

  1. Start mitmproxy: mitmweb --listen-port 8080 -w ~/capture.flow
  2. Route Trader+ through the proxy (system proxy + CA cert)
  3. Perform the target action in Trader+
  4. Analyze the capture: extract endpoints, request/response shapes
  5. Create Pydantic model, API module, client integration, and tests

Model Codegen Pipeline

The SDK includes a code generation tool that produces Pydantic v2 models from C# source definitions. This is used to generate the 1,224 models in models/generated/.

# Generate all categories (enums, API DTOs, internal models)
python -m tools.codegen.run --category all

# Generate specific category
python -m tools.codegen.run --category enums
python -m tools.codegen.run --category api
python -m tools.codegen.run --category internal

# Preview without writing files
python -m tools.codegen.run --category all --dry-run --verbose

The pipeline:

  1. Scans C# source directories configured in tools/codegen/config.py
  2. Parses classes, enums, and properties via regex patterns
  3. Maps C# types to Python (decimal to Decimal, string to str, nullable to Optional)
  4. Generates Pydantic v2 models with Field(alias="camelCase") and model_config
  5. Writes to src/fidelity_trader/models/generated/{enums,api,internal}/

Full regeneration takes under 1 second.

Version Diff Pipeline

When the Fidelity Trader+ desktop app updates, the version diff pipeline detects changes and produces a structured report of API differences.

Check for App Updates

# Check installed version vs baseline
python -m tools.version_check

# Save current version as baseline
python -m tools.version_check --save

# JSON output
python -m tools.version_check --json

Diff Generated Models

# 1. Snapshot current models (before regenerating)
python -m tools.model_diff --snapshot

# 2. Prepare new source and regenerate
python -m tools.codegen.run --category all

# 3. See what changed (semantic diff)
python -m tools.model_diff

# 4. JSON output for automation
python -m tools.model_diff --json

# 5. Compare arbitrary directories
python -m tools.model_diff --old /path/old --new /path/new

The diff report shows changes at the semantic level — not line diffs, but structured changes:

=== Model Diff Report ===
  2 new classes, 0 removed, 1 changed
  1 new enums, 0 removed, 0 changed

NEW CLASSES (2):
  + api/trade:CryptoOrderRequest (8 fields)
  + internal/positions:CryptoPositionDetail (5 fields)

CHANGED CLASSES (1):
  ~ api/orders:OrderSummaryV3:
    + crypto_count: int (alias: "cryptoCount")

NEW ENUMS (1):
  + enums/trade:CryptoActionType (BUY=0, SELL=1)

Full Version Update Workflow

# 1. Detect update
python -m tools.version_check
# -> "UPDATE DETECTED: v4.5.1.4 -> v4.5.2.0"

# 2. Snapshot current state
python -m tools.model_diff --snapshot

# 3. Prepare new C# source (manual step)

# 4. Regenerate models
python -m tools.codegen.run --category all

# 5. Review changes
python -m tools.model_diff

# 6. Update baseline
python -m tools.version_check --save

See docs/BACKLOG.md for the full backlog.