QuantDingerQuantDingerv5.7.1 Docs Docs home
中文 GitHub
View Markdown source

Alpaca execution-fee reconciliation

Alpaca can report an order fill before its authoritative fee evidence is available. QuantDinger therefore treats fill quantity and fee finality as separate states: the trade may already exist while its fee is still marked pending.

What the interface means

Display Meaning
Pending confirmation The fill is recorded, but no authoritative fee or zero-fee evidence has been received yet.
A non-zero fee Alpaca activity data reported an execution cost and QuantDinger stored it as an actual fee.
$0.00 after confirmation Alpaca explicitly reported zero commission; this is stored as actual_zero, not guessed from a missing value.

The top cost cards aggregate persisted execution records. A fee that is still pending is not silently converted to zero and is not included as an authoritative cost until reconciliation completes.

Reconciliation flow

  1. The order and its fill quantity are persisted as soon as the broker confirms execution.
  2. When the fill payload does not contain authoritative fee evidence, the trade remains fee_status=pending.
  3. The Alpaca synchronization worker retries completed orders that still contain pending-fee trades after the configured retry interval.
  4. Authoritative broker activity data is normalized into a currency-by-currency fee breakdown.
  5. QuantDinger converts the breakdown into quote currency where possible and updates the matching persisted trades proportionally by executed value.
  6. The trade is finalized as actual for a non-zero fee or actual_zero for an explicitly confirmed zero fee. The evidence source is stored as rest.

This process is idempotent: only trades whose fee state is still pending are backfilled, so repeated synchronization does not charge the same fee twice.

Operational checks

If a fee remains pending longer than expected:

  1. Confirm the trading worker is healthy and has access to the same database as the API.
  2. Verify the Alpaca credential is active and can read orders and account activities.
  3. Confirm the pending order has an exchange order ID and a positive filled quantity.
  4. Check trading-worker logs for alpaca_fill_sync, authentication errors, or activity-query failures.
  5. Verify the relevant qd_strategy_trades row still has fee_status=pending; completed reconciliation should show actual or actual_zero and a fee_source.

Do not manually replace a pending fee with zero merely because the broker has not returned it yet. That would turn missing evidence into false accounting data.

Scope

This guide describes QuantDinger's Alpaca strategy-execution ledger. Broker statements and Alpaca's own account activity remain the final external source for account-level charges. Regulatory, activity, ADR, interest, and other broker-level costs may arrive independently from per-fill commission and are displayed separately when available.