Skip to content

Update README.md #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mandoyu32-droid wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README.md #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
94 changes: 32 additions & 62 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,32 @@
# Webull OpenAPI Python SDK

Note: This is the new version of the Webull SDK, currently applicable only to Webull Hong Kong, Webull US, Webull JP, Webull SG, Webull TH, Webull AU, Webull MY, Webull UK, Webull BR, Webull MX, Webull ZA, or Webull EU customers.

Webull OpenAPI aims to provide quantitative trading investors with convenient, fast and secure services. Webull aims to help every quant traders achieve flexible and changeable trading or market strategies.

The main function:

Trading management: create, modify, cancel orders, etc.

Market information: You can query stocks/ETFs and other related market information through the HTTP interface.

Account Information: Query account balance and position information.

Subscription to real-time information: Subscribe to order status changes, market information, etc.

## Requirements

- Please first generate the app key and app secret on the Webull official website.

| Broker | Link |
|-----------|-------------------------------------------------|
| Webull HK | https://www.webull.hk/open-api |
| Webull US | https://www.webull.com/center#openApiManagement |
| Webull JP | https://www.webull.co.jp/center/openapi/manage |
| Webull SG | https://www.webull.com.sg/open-api-management|
| Webull TH | https://www.webull.co.th/open-api-management |
| Webull AU | https://www.webull.com.au/open-api-management |
| Webull MY | https://www.webull.com.my/open-api-management |
| Webull UK | https://www.webull-uk.com/open-api-management |
| Webull BR | https://www.webull.com.br/open-api-management |
| Webull MX | https://www.webull.com.mx/open-api-management |
| Webull ZA | https://www.webull.co.za/open-api-management |
| Webull EU | https://www.webull.eu/open-api-management |
- Requires Python 3.8 through 3.14.

## Interface Protocol

The bottom layer of Webull OpenAPI provides three protocols, HTTP / GRPC / MQTT, to support functions and features like trading, subscriptions for changes of order status and real-time market quotes.

| Protocol | Description |
|----------|----------------------------------------------------------------------------------------------------------------|
| HTTP | It mainly provides interface services for data such as tradings, accounts, candlestick charts, snapshots, etc. |
| GRPC | 1. Provide real-time push messages for order status changes. |
| MQTT | Provides data services for real-time market conditions. |

## Developer documentation

| Broker | Link |
|-----------|------------------------------------------|
| Webull HK | https://developer.webull.hk/apis/docs |
| Webull US | https://developer.webull.com/apis/docs |
| Webull JP | https://developer.webull.co.jp/apis/docs |
| Webull SG | https://developer.webull.com.sg/apis/docs |
| Webull TH | https://developer.webull.co.th/apis/docs |
| Webull AU | https://developer.webull.com.au/apis/docs |
| Webull MY | https://developer.webull.com.my/apis/docs |
| Webull UK | https://developer.webull-uk.com/apis/docs |
| Webull BR | https://developer.webull.com.br/apis/docs |
| Webull MX | https://developer.webull.com.mx/apis/docs |
| Webull ZA | https://developer.webull.co.za/apis/docs |
| Webull EU | https://developer.webull.eu/apis/docs |
# Low-risk HMM regime bot (SPY, long-only, paper-first)

## What changed to cut risk (vs. the first plan)
| Area | Before | Now |
|---|---|---|
| Max equity exposure | 95-100% | **70%**, never leveraged, rest in cash |
| Hard drawdown halt | 10% | **6%** -> flat + halt, manual reset live |
| Soft drawdown | none | **3%** -> exposure capped at 35% |
| Daily loss limit | optional | **-1.5%** -> flat next bar |
| Vol targeting | none | exposure <= 10% / realized vol |
| Trend filter | none | below 200d SMA -> max 40% |
| Crash override | none | P(high-vol state) >= 60% -> cash |
| Re-entry | immediate | **3 confirming bars, +20% per bar**; exits are immediate |
| Training window | 252d | **504d** (more stable fits), states sorted by volatility |
| Execution | same bar | signal at close t, trade at **open t+1**, 5 bps/side cost |
| Go-live | flag | `paper=True`, `dry_run=True` by default; live needs `ALLOW_LIVE=YES` |

## Run
pip install -r requirements.txt
python -m unittest discover -s tests -v # 14 tests, incl. look-ahead checks
python backtest.py --csv data/SPY.csv # real data: columns date,open,high,low,close,volume
python backtest.py # synthetic data, offline demo only

Live (paper): set `ALPACA_API_KEY` / `ALPACA_SECRET_KEY`, then `python main.py --once`
(dry-run logs orders only). Set `LiveConfig.dry_run=False` to send paper orders.
Create a file named `KILL` to flatten and stop. After a halt: `python main.py --reset-halt`.

## Pre-live checklist
1. Backtest on 15+ years of real SPY (include 2008, 2020, 2022). Treat anything that looks great as a bug first.
2. Dry-run, then paper trade 2-3 months; compare fills with the 5 bps assumption.
3. Confirm after-hours orders queue for the next open on your Alpaca account (AlpacaBroker is untested offline).
4. Only then consider small real money. Nothing here guarantees profit or prevents loss.