Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,16 @@
</picture>
</a>
</p>
<p>
<a href="https://www.nvidia.com/en-us/startups/" title="Open Byte Inc. has joined NVIDIA Inception">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/badges/nvidia-inception-member-dark.png">
<img src="docs/badges/nvidia-inception-member.png" alt="NVIDIA Inception Program" width="64" align="middle">
</picture>
</a>
&nbsp;&nbsp;
<strong>Open Byte Inc. has joined NVIDIA Inception.</strong>
</p>
</div>

> **Want to contribute?** Explore the
Expand Down
8 changes: 8 additions & 0 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,14 @@
<a href="https://github.com/orgs/OpenByteInc/projects/1/views/4"><img src="https://img.shields.io/github/issues/OpenByteInc/QuantDinger/ready%20for%20contributors?style=flat-square&label=Ready%20tasks&color=0E8A16" alt="Tasks ready for contributors"></a>
</p>

<p><sub>生态计划成员</sub></p>
<p>
<a href="https://www.nvidia.com/en-us/startups/" title="Open Byte Inc. 已加入 NVIDIA Inception">
<img src="docs/badges/nvidia-inception-member.png" alt="NVIDIA Inception 会员徽章" width="210">
</a>
</p>
<p><sub>Open Byte Inc. 已加入 NVIDIA Inception。</sub></p>

<p><sub>赞助支持</sub></p>
<p>
<a href="https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=quantdinger" title="Atlas Cloud — AI inference sponsor">
Expand Down
2 changes: 1 addition & 1 deletion backend_api_python/requirements.lock
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ markdown-it-py==4.2.0
markupsafe==3.0.3
marshmallow==4.3.1
mdurl==0.1.2
msgpack==1.2.1
msgpack==1.2.3
multidict==6.9.1
multitasking==0.0.13
nest-asyncio==1.6.0
Expand Down
2 changes: 2 additions & 0 deletions backend_api_python/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ confluent-kafka>=2.16.0,<3
# Celery 5.6 / Kombu 5.6 currently require redis-py <6.5. This client remains
# compatible with the Redis 8 server used by the production stack.
redis>=6.4.0,<6.5
# CVE-2026-114613; 1.2.3+
msgpack>=1.2.3,<2
# Durable background jobs and periodic maintenance
celery[redis]>=5.6.3,<6
# Production WSGI server
Expand Down
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ AI-agent access. This documentation describes the current v5 release.
| Use AI research | [AI Research guide](product/AI_RESEARCH.md) | [Strategy workflow](product/STRATEGY_WORKFLOW.md) |
| Run a backtest | [Backtest Center guide](product/BACKTEST_CENTER.md) | [Strategy API V2 guide](trading/STRATEGY_DEV_GUIDE.md) |
| Prepare live trading | [Live-trading safety](trading/LIVE_TRADING_SAFETY.md) | [Security and reporting](security/README.md) |
| Reconcile Alpaca execution fees | [English](trading/ALPACA_FEE_RECONCILIATION.md) | [简体中文](trading/ALPACA_FEE_RECONCILIATION_CN.md) |
| Prepare production | [Production hardening](deployment/PRODUCTION_HARDENING.md) | [Observability](deployment/OBSERVABILITY.md) |
| Deploy from AWS Marketplace | [English](deployment/AWS_MARKETPLACE_DEPLOYMENT.md) | [简体中文](deployment/AWS_MARKETPLACE_DEPLOYMENT_CN.md) |
| Release or scale runtime workers | [Distributed runtime scaling](deployment/DISTRIBUTED_RUNTIME_SCALING.md) | [V6 capacity plan](architecture/V6_HYPERSCALE_ARCHITECTURE_PLAN.md) |
Expand Down Expand Up @@ -125,6 +126,7 @@ ownership or shared state.
- [Strategy API V2 development](trading/STRATEGY_DEV_GUIDE.md)
- [Chart indicator development](trading/INDICATOR_DEV_GUIDE.md)
- [Interactive Brokers](trading/IBKR_TRADING_GUIDE_EN.md)
- Alpaca execution-fee reconciliation: [English](trading/ALPACA_FEE_RECONCILIATION.md) / [简体中文](trading/ALPACA_FEE_RECONCILIATION_CN.md)
- [Live-trading safety](trading/LIVE_TRADING_SAFETY.md)
- [Public universes and point-in-time fundamentals (Chinese)](trading/PUBLIC_UNIVERSE_AND_FUNDAMENTALS_CN.md)
- [Fundamental-data preparation operations (Chinese)](strategies/FUNDAMENTAL_DATA_PREPARATION_CN.md)
Expand Down
Binary file added docs/badges/nvidia-inception-member-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/badges/nvidia-inception-member.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
25 changes: 25 additions & 0 deletions docs/marketing/NVIDIA_INCEPTION_MEMBERSHIP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# NVIDIA Inception announcement copy

## English

Open Byte Inc. has joined NVIDIA Inception.

## 中文

Open Byte Inc. 已加入 NVIDIA Inception。

## Social post

Open Byte Inc. has joined NVIDIA Inception.

QuantDinger: https://github.com/OpenByteInc/QuantDinger

NVIDIA Inception: https://www.nvidia.com/en-us/startups/

## 中文社交媒体文案

Open Byte Inc. 已加入 NVIDIA Inception。

QuantDinger:https://github.com/OpenByteInc/QuantDinger

NVIDIA Inception:https://www.nvidia.com/en-us/startups/
40 changes: 40 additions & 0 deletions docs/trading/ALPACA_FEE_RECONCILIATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# 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.
40 changes: 40 additions & 0 deletions docs/trading/ALPACA_FEE_RECONCILIATION_CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Alpaca 成交手续费对账

Alpaca 可能先返回订单成交,再稍后提供权威的费用记录。因此,QuantDinger 将“已成交”和“手续费已确认”作为两个独立状态:交易记录已经出现时,手续费仍可能显示“待确认”。

## 页面状态说明

| 页面显示 | 含义 |
| --- | --- |
| `待确认` | 成交已入账,但尚未收到权威的手续费或零手续费证据。 |
| 非零手续费 | Alpaca 活动记录返回了成交费用,QuantDinger 已按实际费用入账。 |
| 确认后的 `$0.00` | Alpaca 明确返回零佣金,系统以 `actual_zero` 保存,而不是把缺失值猜成零。 |

顶部成本卡片汇总的是已持久化的执行记录。仍处于待确认状态的费用不会被静默当作零,也不会在对账完成前计入权威成本。

## 对账流程

1. 券商确认成交后,系统立即保存订单和成交数量。
2. 如果成交响应没有权威费用证据,交易保持 `fee_status=pending`。
3. 超过配置的重试间隔后,Alpaca 同步 Worker 会重新检查仍含待确认费用的已完成订单。
4. 系统把券商活动记录标准化为按币种拆分的费用明细。
5. 在可转换时将费用换算为报价币种,并按成交金额比例回填到对应交易记录。
6. 非零费用保存为 `actual`;明确确认的零费用保存为 `actual_zero`;证据来源记录为 `rest`。

该过程具备幂等性:只有手续费状态仍为待确认的交易才会被回填,因此重复同步不会重复计费。

## 运维排查

如果手续费长时间保持待确认:

1. 确认 trading worker 正常,并且与 API 连接同一个数据库。
2. 确认 Alpaca 凭据有效,且具备读取订单和账户活动的权限。
3. 确认待处理订单已有券商订单 ID,且成交数量大于零。
4. 在 trading-worker 日志中检查 `alpaca_fill_sync`、鉴权错误或活动查询失败。
5. 检查对应 `qd_strategy_trades` 记录:未完成时为 `fee_status=pending`;完成后应为 `actual` 或 `actual_zero`,并带有 `fee_source`。

不要因为券商暂时未返回费用,就手动把待确认费用改成零。这会把“缺少证据”错误地变成“零费用”的会计事实。

## 适用范围

本文描述 QuantDinger 的 Alpaca 策略执行账本。账户层面的最终费用仍以 Alpaca 对账单和账户活动为外部权威来源。监管费、活动费、ADR 费、利息及其他券商级费用可能独立于单笔成交佣金到达,并在数据可用时分项展示。
Loading