VBrokers Trader

Automate trading on VBrokers (华盛通 VCL HK) via the OpenAPI Gateway running locally.

Prerequisites

OpenAPI Gateway must be running locally (GUI app: 华盛通OpenAPIGateway.app)
Gateway URL: http://127.0.0.1:11111
AES key for password encryption: provided during account setup (see references/api-reference.md)
Python packages: pycryptodome (pip install pycryptodome)

Quick Start

Copy scripts/vbrokers_client.py to your project and import it:

import sys
sys.path.insert(0, '/path/to/skill/scripts')
import vbrokers_client as vb

# 1. Login (required after Gateway restart)
vb.trade_login("your_trading_password")

# 2. Check account
funds = vb.get_account_funds("P")   # P=US, K=HK

# 3. Get real-time quote (use correct mktTmType for time segment)
quote = vb.get_quotes_batch(["AAPL"], session=-1)  # -1=pre-market

# 4. Place order
result = vb.place_order("AAPL", "P", "1", 1, 180.00)  # BUY 1 share limit $180

# 5. Check positions
positions = vb.get_positions("P")

Key Concepts

Request Format (Critical)

All HTTP requests must use nested params:

{"timeout_sec": 10, "params": {"exchangeType": "P", ...}}

Exchange Types

Code	Market
`P`	US Stocks
`K`	HK Stocks
`v`	深股通
`t`	沪股通

Session Types (for orders)

Value	Meaning
`"0"`	Regular hours only
`"1"`	Extended (pre + post market) — use for US stocks

mktTmType (for real-time quotes)

Value	Segment	Beijing Time
`1`	Regular (盘中)	22:30–05:00
`-1`	Pre-market (盘前)	17:00–22:30
`-2`	After-hours (盘后)	05:00–09:00
`-3`	Night session (夜盘)	09:00–17:00
omit	Default (last close)	—

⚠️ Always specify mktTmType for real-time prices — omitting it returns the previous close.

Password Encryption

Trading password must be AES-ECB encrypted before login:

# Already handled in vbrokers_client.py via encrypt_password()
# Key: base64-encoded 24-byte AES key (provided at account setup)

Common Workflows

Stop-Loss / Take-Profit Monitor

result = vb.check_stop_loss("AAPL", "P", cost_price=150.0,
                             stop_loss_pct=0.08, take_profit_pct=0.10)
# Returns: {"action": "hold"/"stop_loss"/"take_profit", "current_price": ..., "pnl_pct": ...}
if result["action"] == "stop_loss":
    vb.place_order("AAPL", "P", "2", qty, 0, entrust_type="5")  # market sell

Batch Quotes with Time Segment

from datetime import datetime, timezone, timedelta
bj_hour = (datetime.now(tz=timezone.utc) + timedelta(hours=8)).hour
# Determine correct mktTmType based on Beijing time
session = 1 if (bj_hour >= 22 or bj_hour <= 4) else -1 if bj_hour >= 17 else -2 if bj_hour <= 8 else -3
quotes = vb.get_quotes_batch(["AAPL", "TSLA", "NVDA"], session=session)

Cancel All Orders

vb.cancel_all_orders("P")  # Cancel all pending US stock orders

API Reference

For complete endpoint documentation, parameters, and response schemas: → See references/api-reference.md

For the full verified client implementation: → See scripts/vbrokers_client.py

vbrokers-trading

Installation