git:20260725.777afdb to v1.0.0

---

---

# Broker API Versioning & Migration Playbook

This skill provides a rigorously engineered framework for migrating institutional trading infrastructure between broker API versions. Upgrading APIs (e.g., from V1 to V2 REST/FIX endpoints) poses significant risks including downtime, broken schema mappings, unexpected latency spikes, and corrupted order state.

## Core Capabilities

1. **Shadow Traffic Auditing**: Replicates read traffic (e.g., fetching positions, order status) to both the legacy and target API versions to detect schema drifts, type mismatches, and latency regressions without impacting actual trading.

2. **Canary Traffic Cutover**: Deterministically or probabilistically routes a controlled percentage of order flow (writes) to the new API version.

3. **Instant Rollback**: State machine driven instantaneous rollback mechanisms to revert traffic to the legacy version if error rates or latency thresholds are breached.

4. **Latency Tracking**: Thread-safe concurrent latency monitoring to ensure the new API meets execution speed requirements.

## Directory Structure

- `scripts/api_migrator.py`: The core `BrokerAPIVersionMigrator` thread-safe state machine and engine.

- `scripts/test_api_migrator.py`: Comprehensive test suite verifying the migrator's quantitative logic.

- `references/workflows.md`: Detailed step-by-step institutional migration workflows.

- `references/standards.md`: API migration standards and thresholds for quant systems.

- `assets/checklist.md`: The operational checklist for executing a migration.

## Usage

Use the migrator class to manage the lifecycle of an API upgrade within your trading engines. Start in `V1_ONLY`, proceed to `SHADOW_MODE` for reads, move to `CANARY_CUTOVER` for writes, and finalize with `V2_ONLY`. Always have `ROLLBACK_V1` bound to an emergency kill switch.