Alpha Trade Sync

Purpose

This dashboard now syncs Alpha option-trade rows from the canonical Alpha export endpoint in ~/server instead of the old placeholder OMS JSON shape.

The sync is:

• portfolio-scoped, not crypto-currency-scoped
• cursor/watermark-based, not single-shot limit based
• strict about contract validation
• explicit about per-contract price vs total USD premium

Required Backend Configuration

Set these on the backend service:

• ALPHA_TRADE_FEED_URL
  • Full internal export URL, for example:
  • https://api.bitwiseinvestments.com/api/v1/alpha/optionTrades/export
• ALPHA_TRADE_FEED_API_KEY
  • API key with alphaAccess permission for the ~/server export endpoint
  • Send the raw key in the Authorization header; do not prefix it with Bearer
• ALPHA_TRADE_FEED_PORTFOLIOS
  • Comma-separated Alpha portfolios; production is currently configured as IMST,ICOI

Optional:

• ALPHA_TRADE_FEED_INCLUDE_PENDING
  • Default false
  • Operators can override this per run with the Include pending checkbox on /trades
• ALPHA_TRADE_FEED_TIMEOUT_SECONDS
  • Default 20

Stored Trade Semantics

For synced Alpha rows:

• price: per-contract price in price_currency
• contract_multiplier: source multiplier from Alpha
• quantity: filled contract count
• premium_usd: total trade premium in USD
• fees_usd: total USD fees for the trade
• trade_status: source trade status
• recon_status: source-provided Alpha reconciliation status

Do not interpret price as total dollars.

Market Proxy Mapping

Alpha rows store the traded underlying, for example MSTR or COIN. Many dashboard opportunity and regime signals are keyed by crypto market, for example BTC, ETH, or SOL. The backend resolves this split through back-end/market_proxy.py.

Current production mappings:

Unknown symbols return unmapped with market_proxy = null. The dashboard must not silently default an unknown Alpha underlying to BTC. Downstream enrichment should skip or explicitly label unmapped trades until a mapping is added to back-end/market_proxy.py.

Trade-Time Market Context Backfill

The trade-performance phase adds a backend backfill path:

POST /api/internal/trades/context/backfill

The endpoint is admin-protected and defaults to dry run. It joins Alpha-synced trades to nearest available dashboard context using the market proxy mapping above.

Currently captured when available:

• market proxy, mapping method, mapping confidence, and mapping quality
• nearest gex_hourly spot and GEX imbalance
• nearest vol_metrics_snapshots DVol, VRP, 30d IV, and 30d RV
• DVol percentile over the lookback window
• gamma regime from historical GEX imbalance thresholds
• context quality and missing-field list

Currently not captured by this first backfill:

• smile rich/cheap state at exact trade time
• 24h volume and open interest at exact trade time

Smile is intentionally not sourced for Alpha trade rows in this phase. BTC smile is still useful on market analytics pages, but it is not stamped onto MSTR/COIN option trades as a contract-level smile proxy. Other missing fields are persisted as unavailable/missing until a later enrichment step can source them safely. Missing context is not converted to zero.

Execution Benchmark Backfill

Execution-quality enrichment uses a separate admin-protected backfill path:

POST /api/internal/trades/execution-benchmarks/backfill

The benchmark hierarchy is strict:

1. Use a fresh Amberdata TradFi level-1 quote for the actual traded underlying and contract when available.
2. Mark quote-derived values as stale if the nearest quote is outside the configured tolerance.
3. Use a surface/model mark only as estimated; never populate bid, ask, or mid from a model.
4. Return unavailable when no defensible quote or estimate exists.

For current Alpha scope:

Direction signs:

• Buy slippage uses fill_price - benchmark_mid; positive means worse than mid.
• Sell slippage uses benchmark_mid - fill_price; positive means worse than mid.

The dashboard must not fabricate bid, ask, mid, or slippage when quote data is missing.

Position Lifecycle View

Alpha rows are executions, not positions. The dashboard groups them into derived option-contract lifecycles with:

GET /api/internal/trades/positions?source=alpha_sync

Grouping keys:

• source portfolio
• traded underlying
• option symbol or instrument
• option type
• strike
• expiry

Accounting rules:

• Each execution quantity is treated as a positive contract count; direction controls the sign.
• Buys increase long exposure or close short exposure.
• Sells increase short exposure or close long exposure.
• Matching uses FIFO within the grouped option contract.
• average_open_price is weighted by remaining quantity and contract multiplier.
• total_gross_premium_usd and net_premium_cashflow_usd are populated only when every execution in the lifecycle has a defensible USD premium.
• known_gross_premium_usd and known_net_premium_cashflow_usd show the sum of available premium rows when premium data is incomplete.
• Fees follow the same pattern: total_fees_usd requires complete fee data; known_fees_usd reports the known subset.
• Derived lifecycle cashflow is calculated for internal investigation, but it is not displayed as user-facing realized P&L until validated against authoritative accounting or explicit source open/close intent.

Lifecycle states:

Lifecycle quality:

Flips are allowed and flagged. For example, buying 5 contracts and then selling 8 contracts closes 5 long contracts and opens 3 short contracts. The lifecycle remains deterministic, but lifecycle_flags includes flipped so downstream screens can disclose the path.

Opportunity Alignment

Opportunity alignment is a signal-consistency score, not a P&L score. It asks whether the trade direction matched the dashboard opportunity backdrop at execution time.

GET /api/internal/trades/opportunity-alignment?source=alpha_sync

Assumption boundary:

• strategy_intent is unknown until a future workflow explicitly tags intent.
• Buy-option rows are scored under an assumed_strategy of long_vol.
• Sell-option rows are scored under an assumed_strategy of short_vol.
• Call versus put is carried through the output, but the first scoring pass does not infer directional delta intent from option type.

Scoring rules:

Confidence is separate from score. It is reduced when:

• context is stale, unavailable, or unmapped
• the Alpha underlying uses a proxy mapping such as MSTR/COIN to BTC
• stationarity is unstable or insufficient
• signal coverage is incomplete

Labels:

The API also returns aggregate summaries by portfolio, underlying, gamma regime, signal, and month.

Outcome And Regime Attribution

Outcome attribution measures what happened after entry only when a sourced forward mark is available.

GET /api/internal/trades/outcomes?source=alpha_sync&horizons=1,7,30

By default the endpoint reads persisted forward outcome marks from trade_forward_outcome_marks. It returns explicit pending or unavailable horizon outcomes when no usable persisted mark exists. When fetch_marks=true, the backend can look up Amberdata TradFi level-1 quotes at each requested horizon for a small ad hoc batch, but production use should backfill marks through:

POST /api/internal/trades/outcomes/backfill

The backfill is admin-protected, defaults to dry run, and upserts rows keyed by (source, source_trade_id, horizon_key).

Outcome states:

Mark quality:

P&L rules:

• Buy-option P&L before fees: mark_premium_usd - entry_premium_usd.
• Sell-option P&L before fees: entry_premium_usd - mark_premium_usd.
• mark_premium_usd = mark_price * quantity * contract_multiplier.
• pnl_after_fees_usd is populated only when fees_usd is available.
• Missing marks, stale marks, missing premium, or missing quantity produce null P&L, never zero.

Expiry outcomes remain unavailable unless a sourced quote or settlement mark exists. The dashboard should not silently substitute intrinsic/model expiry values.

Aggregates answer which portfolios, underlyings, gamma regimes, alignment labels, and DVol buckets produced positive/negative sourced outcomes for a selected horizon.

Sync State

Persisted in internal_trade_sync_state:

• last_successful_cursor
• last_successful_watermark
• last_successful_sync_at
• last_error
• scope_key

Scope key format is portfolio-based:

• portfolio_names=<sorted list>|include_pending=<true|false>

Operator Workflow

Use the OMS/PMS Sync card on /trades.

Dry run

Use Dry run for a preview.

Check:

• fetched row count
• normalized row count
• rejected row count
• inserted / updated / unchanged breakdown
• quantity delta
• premium delta
• unmatched source trade ids
• unmatched local trade ids
• next watermark

Full-scope sync diagnostic

Enable the full-scope diagnostic before the dry run when you need a complete sync-completeness check for the configured scope.

Use this before interpreting Performance from a freshly changed feed scope, or after changing sync logic.

Real sync

Turn Dry run off only after the preview looks correct.

After a real sync:

• confirm last successful sync time updates
• confirm next watermark advances
• confirm the trade table shows source_portfolio, trade_status, recon_status
• confirm price is shown per contract and premium in USD

Verification Checklist

Before moving the trade-sync milestone to In Review:

• ALPHA_TRADE_FEED_URL points at the canonical server export endpoint
• ALPHA_TRADE_FEED_API_KEY has alphaAccess permission
• configured portfolio names resolve in Alpha
• dry run succeeds without contract-validation surprises
• full-scope diagnostic shows acceptable quantity and premium deltas
• re-running a real sync does not duplicate rows
• updated rows show changed-field evidence when the source changed
• the trade table labels price, premium, fees, and P&L unambiguously

Known Scope Boundary

This milestone makes ingestion and valuation semantics explicit and adds a bounded path for sourced forward marks. If Amberdata TradFi coverage is missing, stale, or not entitled for a synced row, P&L should remain blank rather than guessed. Expiry and authoritative realized P&L remain unavailable until backed by settlement, source accounting, or another approved source.