Skip to content

Commit 9dd1c7a

Browse files
PigbibiPigbibi
committed
Initial Firstrade platform runtime
0 parents  commit 9dd1c7a

23 files changed

Lines changed: 1941 additions & 0 deletions

‎.env.example‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Required for login.
2+
FIRSTRADE_USERNAME=
3+
FIRSTRADE_PASSWORD=
4+
5+
# Pick one MFA path when the account requires it.
6+
# TOTP is best for unattended dry-run validation if enabled on the account.
7+
FIRSTRADE_MFA_SECRET=
8+
FIRSTRADE_PIN=
9+
FIRSTRADE_MFA_EMAIL=
10+
FIRSTRADE_MFA_PHONE=
11+
FIRSTRADE_MFA_CODE=
12+
13+
# Optional when the login returns multiple accounts.
14+
FIRSTRADE_ACCOUNT=
15+
16+
# Shared US equity strategy runtime.
17+
STRATEGY_PROFILE=
18+
FIRSTRADE_DRY_RUN_ONLY=true
19+
FIRSTRADE_STRATEGY_ADAPTER_SOURCE_PLATFORM=longbridge
20+
ACCOUNT_PREFIX=FIRSTRADE
21+
ACCOUNT_REGION=US
22+
23+
# Runtime safety controls.
24+
FIRSTRADE_COOKIE_DIR=.runtime/firstrade-cookies
25+
FIRSTRADE_ENABLE_LIVE_TRADING=false
26+
FIRSTRADE_RUN_SMOKE_ON_HTTP=false
27+
FIRSTRADE_SMOKE_SYMBOL=SPY

‎.github/dependabot.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "pip"
4+
directory: "/"
5+
schedule:
6+
interval: "weekly"
7+

‎.github/workflows/ci.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
jobs:
9+
test:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v5
13+
- uses: actions/setup-python@v6
14+
with:
15+
python-version: "3.12"
16+
- name: Install dependencies
17+
run: |
18+
python -m pip install --upgrade pip
19+
python -m pip install -r requirements.txt
20+
- name: Run tests
21+
run: python -m pytest -q
22+

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.env
2+
.env.*
3+
!.env.example
4+
.venv/
5+
.pytest_cache/
6+
__pycache__/
7+
*.py[cod]
8+
.runtime/
9+
ft_cookies*.json
10+

‎CONTRIBUTING.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Contributing
2+
3+
Keep this repository conservative. Firstrade support is based on an unofficial
4+
reverse-engineered package, so changes should preserve local safety controls and
5+
make failure modes obvious.
6+
7+
Rules for contributions:
8+
9+
- Do not remove the default dry-run behavior.
10+
- Do not weaken the live order gates in `application/firstrade_client.py`.
11+
- Do not add credentials, cookies, account IDs, balances, or raw order payloads
12+
to examples or tests.
13+
- Keep upstream attribution in `NOTICE.md`.
14+
- Prefer small tests that mock the broker boundary. Do not require live
15+
Firstrade credentials in CI.
16+
17+
Run the local unit tests before opening a pull request:
18+
19+
```bash
20+
.venv/bin/python -m pytest -q
21+
```
22+

‎LICENSE‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
MIT License
2+
3+
Copyright (c) 2026 QuantStrategyLab
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
22+

‎NOTICE.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Notices
2+
3+
This repository integrates with the third-party `firstrade` Python package:
4+
5+
- Project: https://github.com/MaxxRK/firstrade-api
6+
- Package: https://pypi.org/project/firstrade/
7+
- License: MIT
8+
9+
`firstrade` is an unofficial, reverse-engineered Firstrade API client. It is
10+
not affiliated with, endorsed by, or supported by Firstrade Securities Inc.
11+
12+
Keep this notice and the upstream license attribution when distributing this
13+
repository or derivative work.
14+

‎README.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Firstrade Platform
2+
3+
Firstrade platform layer for QuantStrategyLab-style US equity runtimes.
4+
5+
This repository wraps the unofficial `firstrade` Python package and exposes a
6+
QuantStrategyLab platform layer for shared `UsEquityStrategies` profiles. It
7+
provides QuantPlatformKit broker ports for quotes, OHLC history, portfolio
8+
snapshots, and guarded order submission.
9+
10+
## Status
11+
12+
- API source: unofficial, reverse-engineered `firstrade` package
13+
- Upstream package: https://pypi.org/project/firstrade/
14+
- Upstream repository: https://github.com/MaxxRK/firstrade-api
15+
- Local default order mode: dry-run / preview only
16+
- Live order path: blocked unless both CLI confirmation and
17+
`FIRSTRADE_ENABLE_LIVE_TRADING=true` are set
18+
- Strategy domain: shared `us_equity` profiles from `UsEquityStrategies`
19+
20+
This project is not affiliated with, endorsed by, or supported by Firstrade
21+
Securities Inc. The upstream API can break without notice when Firstrade
22+
changes its web/mobile backend.
23+
24+
## Why This Exists
25+
26+
Firstrade does not expose the same kind of official retail trading API as
27+
brokers such as IBKR or LongPort. The integration here is therefore treated as
28+
an experimental platform layer, not a production-grade broker connector.
29+
30+
Use it first for:
31+
32+
- login/MFA validation
33+
- account and position reads
34+
- quote/OHLC checks
35+
- dry-run order preview
36+
- very small, explicitly approved live validation only after manual review
37+
38+
## Strategy Runtime Boundary
39+
40+
This platform is intended to mirror the role of `InteractiveBrokersPlatform`,
41+
`CharlesSchwabPlatform`, and `LongBridgePlatform`: strategy logic stays in
42+
`UsEquityStrategies`, while this repository owns Firstrade authentication,
43+
account reads, market data reads, order translation, runtime safety controls,
44+
and deployment wiring.
45+
46+
Firstrade is not yet a first-class `platform_id` inside the pinned
47+
`UsEquityStrategies` version. Until that support lands upstream, this
48+
repository reports runtime identity as `firstrade` while loading the same
49+
value-native strategy adapter shape used by LongBridge/Schwab. The default
50+
source is:
51+
52+
```bash
53+
FIRSTRADE_STRATEGY_ADAPTER_SOURCE_PLATFORM=longbridge
54+
```
55+
56+
Print the current Firstrade strategy matrix:
57+
58+
```bash
59+
.venv/bin/python scripts/print_strategy_profile_status.py
60+
```
61+
62+
The long-term target is first-class `firstrade` coverage in
63+
`UsEquityStrategies` so this bridge can be removed.
64+
65+
## Environment
66+
67+
Copy `.env.example` into your secret manager or shell environment. Do not
68+
commit credentials.
69+
70+
| Variable | Required | Description |
71+
| --- | --- | --- |
72+
| `FIRSTRADE_USERNAME` | Yes | Firstrade login username |
73+
| `FIRSTRADE_PASSWORD` | Yes | Firstrade login password |
74+
| `FIRSTRADE_MFA_SECRET` | Optional | TOTP secret for unattended MFA |
75+
| `FIRSTRADE_PIN` | Optional | PIN flow supported by upstream package |
76+
| `FIRSTRADE_MFA_EMAIL` | Optional | Email OTP recipient selector |
77+
| `FIRSTRADE_MFA_PHONE` | Optional | SMS OTP recipient selector |
78+
| `FIRSTRADE_MFA_CODE` | Optional | One-time OTP code for the current validation run |
79+
| `FIRSTRADE_ACCOUNT` | Optional | Required when multiple accounts are returned |
80+
| `STRATEGY_PROFILE` | Yes for runtime | Shared US equity strategy profile |
81+
| `FIRSTRADE_DRY_RUN_ONLY` | Optional | Defaults to `true` for platform runtime |
82+
| `FIRSTRADE_STRATEGY_ADAPTER_SOURCE_PLATFORM` | Optional | `longbridge` default; `schwab` also allowed |
83+
| `ACCOUNT_PREFIX` | Optional | Alert/log prefix, default `FIRSTRADE` |
84+
| `ACCOUNT_REGION` | Optional | Runtime account scope, default `US` |
85+
| `FIRSTRADE_COOKIE_DIR` | Optional | Cookie cache directory, default `.runtime/firstrade-cookies` |
86+
| `FIRSTRADE_ENABLE_LIVE_TRADING` | Optional | Must be `true` before any live order can be submitted |
87+
| `FIRSTRADE_RUN_SMOKE_ON_HTTP` | Optional | Must be `true` before `/smoke` performs a real login/quote |
88+
89+
## Local Validation
90+
91+
Install dependencies in a venv:
92+
93+
```bash
94+
python3 -m venv .venv
95+
.venv/bin/python -m pip install -r requirements.txt
96+
```
97+
98+
Quote-only smoke check:
99+
100+
```bash
101+
.venv/bin/python scripts/firstrade_smoke_check.py --quote-only --symbol SPY
102+
```
103+
104+
Dry-run order preview for a tiny notional buy:
105+
106+
```bash
107+
.venv/bin/python scripts/firstrade_smoke_check.py \
108+
--preview-order \
109+
--symbol YOUR_SYMBOL \
110+
--side buy \
111+
--notional-usd 5 \
112+
--max-notional-usd 25
113+
```
114+
115+
Live order validation requires all of the following:
116+
117+
- `FIRSTRADE_ENABLE_LIVE_TRADING=true`
118+
- `--live-order`
119+
- `--yes-i-understand-unofficial-api-risk`
120+
- order notional at or below `--max-notional-usd`
121+
122+
Example shape:
123+
124+
```bash
125+
FIRSTRADE_ENABLE_LIVE_TRADING=true \
126+
.venv/bin/python scripts/firstrade_smoke_check.py \
127+
--live-order \
128+
--symbol YOUR_SYMBOL \
129+
--side buy \
130+
--notional-usd 5 \
131+
--max-notional-usd 25 \
132+
--yes-i-understand-unofficial-api-risk
133+
```
134+
135+
The example does not recommend any security. Choose the validation symbol
136+
yourself and confirm Firstrade account permissions, fractional trading
137+
agreement status, market session, and order preview before live use.
138+
139+
## Cloud Run Shape
140+
141+
`main.py` exposes:
142+
143+
- `/` health metadata only
144+
- `/precheck` health metadata only
145+
- `/probe` health metadata only
146+
- `/profiles` shared US equity strategy matrix
147+
- `/smoke` login + quote only when `FIRSTRADE_RUN_SMOKE_ON_HTTP=true`
148+
149+
The HTTP entrypoint does not place orders.
150+
151+
## License And Upstream Compliance
152+
153+
This repository is MIT licensed. The upstream `firstrade` package is also MIT
154+
licensed. Keep `NOTICE.md` and upstream attribution when distributing this
155+
project or derivative work.
156+
157+
Users are responsible for reviewing Firstrade account agreements, platform
158+
terms, applicable law, and the upstream open-source license before using this
159+
integration.
160+
161+
---
162+
163+
## 中文说明
164+
165+
这是一个 QuantStrategyLab 风格的 Firstrade 平台层仓库。它接入的是
166+
`firstrade` 这个非官方、逆向工程 Python 包，不是 Firstrade 官方 API。
167+
168+
当前目标是对齐 `InteractiveBrokersPlatform`、`CharlesSchwabPlatform` 和
169+
`LongBridgePlatform`：策略逻辑放在 `UsEquityStrategies`，这个仓库只负责
170+
Firstrade 登录、账户/行情读取、下单转换、安全闸和部署 wiring。
171+
172+
当前定位是小规模验证到通用美股平台层的过渡：
173+
174+
- 登录和 MFA 验证
175+
- 账户、持仓、行情、OHLC 读取
176+
- dry-run / preview 下单验证
177+
- 在你再次确认后，才允许极小金额实盘验证
178+
- 通用 `us_equity` 策略 profile 的平台层接入
179+
180+
默认所有订单都是 preview。实盘必须同时满足：
181+
182+
- 设置 `FIRSTRADE_ENABLE_LIVE_TRADING=true`
183+
- CLI 使用 `--live-order`
184+
- CLI 使用 `--yes-i-understand-unofficial-api-risk`
185+
- 金额不超过 `--max-notional-usd`
186+
187+
请不要把 Firstrade 登录凭据、MFA secret、cookie 文件提交到 Git。`.env`、
188+
`.runtime/` 和 `ft_cookies*.json` 已经在 `.gitignore` 中。
189+
190+
开源协议方面：本仓库使用 MIT；上游 `firstrade` 包也是 MIT。发布或二次分发
191+
时保留 `NOTICE.md` 和上游项目信息。
192+
193+
注意：当前 `UsEquityStrategies` 尚未内置 `firstrade` 平台 adapter。本仓库
194+
临时复用 LongBridge/Schwab 的 value-native 策略输入形状，并在运行报告中保留
195+
Firstrade 平台身份。后续应在 `UsEquityStrategies` 里补齐 first-class
196+
`firstrade` 兼容矩阵。

‎SECURITY.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Security Policy
2+
3+
This repository integrates with an unofficial, reverse-engineered Firstrade API
4+
client. Treat credentials, cookies, MFA secrets, and debug logs as highly
5+
sensitive.
6+
7+
Do not commit:
8+
9+
- Firstrade username or password
10+
- MFA secret, PIN, OTP codes, or recovery material
11+
- `.runtime/` cookie files
12+
- raw upstream HTTP request/response logs
13+
- account numbers, balances, positions, or order confirmations
14+
15+
Report vulnerabilities privately through the repository security channel after
16+
the repository is published. Until then, keep reports within the QuantStrategyLab
17+
maintainer group.
18+

‎application/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
"""Firstrade platform integration package."""
2+

0 commit comments

Comments
 (0)