diff --git a/README.md b/README.md index 5ea008c1a..aa7f609fd 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,16 @@

+

+ + + + NVIDIA Inception Program + + +    + Open Byte Inc. has joined NVIDIA Inception. +

> **Want to contribute?** Explore the diff --git a/README_CN.md b/README_CN.md index ae32f0398..12b0315b2 100644 --- a/README_CN.md +++ b/README_CN.md @@ -79,6 +79,14 @@ Tasks ready for contributors

+

生态计划成员

+

+ + NVIDIA Inception 会员徽章 + +

+

Open Byte Inc. 已加入 NVIDIA Inception。

+

赞助支持

diff --git a/backend_api_python/requirements.lock b/backend_api_python/requirements.lock index 11acccadc..b0ad7f705 100644 --- a/backend_api_python/requirements.lock +++ b/backend_api_python/requirements.lock @@ -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 diff --git a/backend_api_python/requirements.txt b/backend_api_python/requirements.txt index c6eb31ed6..a287ead11 100644 --- a/backend_api_python/requirements.txt +++ b/backend_api_python/requirements.txt @@ -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 diff --git a/docs/README.md b/docs/README.md index 9fdeab5ba..6a0ab8bde 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) | @@ -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) diff --git a/docs/badges/nvidia-inception-member-dark.png b/docs/badges/nvidia-inception-member-dark.png new file mode 100644 index 000000000..c1cfb1d58 Binary files /dev/null and b/docs/badges/nvidia-inception-member-dark.png differ diff --git a/docs/badges/nvidia-inception-member.png b/docs/badges/nvidia-inception-member.png new file mode 100644 index 000000000..c34ca4b63 Binary files /dev/null and b/docs/badges/nvidia-inception-member.png differ diff --git a/docs/marketing/NVIDIA_INCEPTION_MEMBERSHIP.md b/docs/marketing/NVIDIA_INCEPTION_MEMBERSHIP.md new file mode 100644 index 000000000..823d658f2 --- /dev/null +++ b/docs/marketing/NVIDIA_INCEPTION_MEMBERSHIP.md @@ -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/ diff --git a/docs/trading/ALPACA_FEE_RECONCILIATION.md b/docs/trading/ALPACA_FEE_RECONCILIATION.md new file mode 100644 index 000000000..b3b8469db --- /dev/null +++ b/docs/trading/ALPACA_FEE_RECONCILIATION.md @@ -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. diff --git a/docs/trading/ALPACA_FEE_RECONCILIATION_CN.md b/docs/trading/ALPACA_FEE_RECONCILIATION_CN.md new file mode 100644 index 000000000..a75c2e143 --- /dev/null +++ b/docs/trading/ALPACA_FEE_RECONCILIATION_CN.md @@ -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 费、利息及其他券商级费用可能独立于单笔成交佣金到达，并在数据可用时分项展示。