kelly-invest-webull
Busabase-backed, read-only App-in-Skill portfolio dashboard that aggregates Webull brokerage holdings (accounts, positions, cash/margin, market value, unrealized P/L, day change, buying power). Use wh
SKILL.mdskills/kelly-invest-webull/SKILL.md
GitHubKelly Invest (Webull)
Overview
Kelly Invest (Webull) is a Busabase Cloud App-in-Skill. Its canonical product surface is the AirApp in Busabase, not a separate local-data product. The same Hono source supports an explicitly requested local preview with OAuth connection bootstrap. Use this skill as Kelly's read-only Webull portfolio operator: an Overview (totals, unrealized P/L, day change, cash, allocation donut, top movers, insights), a sortable Positions table, an Accounts view (cash and margin), and a per-symbol Position detail pane.
Default behavior is AirApp-first. Unless the user explicitly asks only for explanation, give the user the clickable AirApp URL. Start localhost only when local preview/debugging is explicitly requested; it uses the same Busabase resources and never offers another data provider. Use chat-only mode only when the user says "纯聊天", "chat only", "不要打开 UI", or similar.
This is a monitoring dashboard: there is no approval lifecycle and no decisions workflow.
Mandatory Dependencies
- Read and follow
$kelly-app-skill-creatorfor product behavior, visual quality, responsive layout, and the complete canonicalcontent/kelly-invest-webull-app/artifact. - Read and follow
$busabasefor connection, target Space, node discovery, ChangeRequests, review, and merge behavior. - Read and follow
$busabase-app-creatorfor resource modeling, AirApp runtime limits, security, validation, and deployment.
If a dependency is unavailable, preserve this skill's local artifact and product contracts, stop before the unavailable Busabase operation, and report the exact missing dependency. Do not invent a second data backend.
App UI Screenshots
<table> <tr> <td width="50%"><img src="assets/screenshots/overview.webp" alt="Kelly Invest overview"></td> <td width="50%"><img src="assets/screenshots/positions.webp" alt="Kelly Invest positions"></td> </tr> <tr> <td><strong>Overview</strong><br>Portfolio command desk with market value, unrealized P/L, day change, cash, an allocation-by-asset-type donut, and top day movers.</td> <td><strong>Positions</strong><br>Sortable holdings table across symbol, asset type, quantity, average cost, last price, market value, unrealized P/L, and portfolio weight.</td> </tr> <tr> <td width="50%"><img src="assets/screenshots/accounts.webp" alt="Kelly Invest accounts"></td> <td width="50%"><img src="assets/screenshots/detail.webp" alt="Kelly Invest position detail"></td> </tr> <tr> <td><strong>Accounts</strong><br>Per-account view (cash and margin) with net liquidation, total cash, buying power, and the positions held in each account.</td> <td><strong>Position detail</strong><br>Single-symbol view with cost basis, market value, unrealized P/L and percentage, day change, weight, and holding account.</td> </tr> </table>Boundary
- The skill may read Webull account/balance/position data, normalize it, and
write Accounts/Positions/Settings rows into Busabase through the trusted
scripts/sync_webull.mjsprocess only. - The AirApp reads Busabase records only; it is entirely read-only and must
NEVER place, modify, or cancel orders. NEVER move money, transfer,
withdraw, or change account settings. There is no trading path in this
skill by design (
readOnly: true, nowriteProcedures). - Treat all holdings/account data as sensitive. Never commit Webull
credentials,
config.local.json, env files, or raw Webull responses.
Busabase Resources
Three Bases under one application Folder (kelly-invest-webull), declared in
content/kelly-invest-webull-app/app/js/config.js and the generated template sidecars under content/:
accounts: Webull cash and margin accounts (account_id,account_type,display_name,currency,net_liquidation,total_cash,buying_power).positions: holdings per account (position_id=account_id:symbol,symbol,name,asset_type,account_id,quantity,avg_cost,last_price,market_value,cost_basis,unrealized_pnl,unrealized_pnl_pct,day_change,day_change_pct,currency). Weights, totals, and allocation are computed at read time bycontent/kelly-invest-webull-app/app/js/webull-model.js(assembleSnapshot), never stored.settings: two rows —config(sanitized Webull region/base URL/account allowlist, base currency, target allocation, generated_at, warnings — no secrets) andonboarding.
Resources provision lazily through an idempotent Busabase ChangeRequest the
first time the app runs in a Space; see references/portfolio-schema.md for
exact field shapes. The AirApp never writes to any Base — only the trusted
sync script does.
Data Provider — Real Webull Integration
The skill reads Webull; the app only ever reads the normalized Busabase snapshot.
lib/data-provider/webull.ts's field-mapping and credential-resolution logic (mapAccount,mapPosition,normalizeAssetType,resolveWebullCredentials) was ported verbatim intocontent/kelly-invest-webull-app/app/js/webull-model.js, shared by both the browser (forassembleSnapshot/computeInsights) and the trusted sync script (for the Webull-specific mapping).scripts/sync_webull.mjsis the only process that writes to Busabase. It resolves Webull App Key / App Secret from env vars named in local config (config.webull.app_key_env/app_secret_env, defaultsKELLY_INVEST_WEBULL_APP_KEY/KELLY_INVEST_WEBULL_APP_SECRET), fetches live account/balance/position data, and writes normalized rows viabases.createChangeRequest/records.changeRequestwith its ownBUSABASE_BASE_URL/BUSABASE_API_KEY/BUSABASE_SPACE_IDcredentials (autoMerge: true).- Webull has no first-party Node SDK — the official SDK is
webull-openapi-python-sdk(Python), and Webull's wire-level signing/endpoint shape is not published outside that SDK (the retiredwebull.tsadapter itself never implemented raw HTTP calls, only the credential + mapping logic, for the same reason).scripts/sync_webull.mjstherefore shells out toscripts/webull_bridge.py, which calls the exact SDK methods documented in the original adapter's comments (get_account_list(),get_account_balance(account_id),get_account_positions(account_id)). Confirm the Python SDK's exact import path againsthttps://developer.webull.com/apis/docs/sdk/before first live use. - For a credential-free dry run (e.g. CI, local testing), pass
--fixture <path/to/raw.json>tosync_webull.mjswith a JSON payload shaped like{ "accounts": [...], "positions": [...] }using the raw Webull SDK field names documented inwebull-model.js. - Rate limit is ~10 requests / 30 seconds per App ID; batch and back off.
Run the sync from the skill root:
BUSABASE_BASE_URL=... BUSABASE_API_KEY=... BUSABASE_SPACE_ID=... \
node scripts/sync_webull.mjs
First Run And Onboarding
On invocation, check the config and onboarding Settings rows for
readiness. If absent, guide setup before syncing real holdings.
To connect Webull, the user needs a Webull OpenAPI App Key and App
Secret from Webull's OpenAPI Management/Portal (region id us; approval
typically takes 1-2 business days). A UAT test host exists at
us-openapi-alb.uat.webullbroker.com.
Ask for non-secret setup details only: region, base URL, base currency,
account allowlist, and which env var names hold the App Key / App Secret.
Never ask the user to paste secret values into chat. Secrets belong only in
local env files read by the trusted sync script, and config references them
by name (app_key_env, app_secret_env).
Demo Mode
?demo=1opens a deterministic, fully offline mock portfolio (~10 positions across STOCK/ETF/CRYPTO in one cash and one margin account) with computed P/L for documentation and screenshots.?demo=positions,?demo=accounts, and?demo=detailselect named mock scenes.lang=enorlang=zhforces UI chrome language for screenshots.- Demo mode never reads or writes Busabase and never claims a real connection.
Local App
Default behavior is AirApp-first — give the user the clickable AirApp URL.
Start pnpm --dir content/kelly-invest-webull-app dev only when local preview/debugging is explicitly
requested. UI language supports English and Chinese chrome with an Auto
default; the user is Chinese, keep symbols and provider values in their
original form.
Views
#/overview: total market value, total unrealized P/L (color + %), day change, cash, and allocation-by-asset-type donut plus top day movers and insights.#/positions: sortable table (symbol, name, qty, avg cost, last, market value, unrealized P/L %, weight).#/accounts: cash and margin accounts with net liquidation, cash, buying power.#/accounts/<account_id>: account summary and its filtered positions.#/positions/<symbol>: per-symbol detail pane.#/settings: sanitized setup summary — data provider, Webull region and base URL, credential-readiness booleans, and onboarding state. Never exposes secret values.
Insights
Read-only, deterministic observations computed by computeInsights in
content/kelly-invest-webull-app/app/js/webull-model.js (ported verbatim from the retired
content/kelly-invest-webull-app/server/insights.ts): single_position_concentration,
crypto_concentration, allocation_drift, cash_drag, negative_cash,
top_gainer, top_laggard. Neutral facts/flags, never advice or actions —
no buy/sell/rebalance suggestions.
File Contract
Read references/portfolio-schema.md before editing the app,
content/kelly-invest-webull-app/app/js/config.js, content/kelly-invest-webull-app/app/js/webull-model.js, or
scripts/sync_webull.mjs.
Safety
- Read-only by design. Prefer read-only Webull scopes/credentials.
- Do not invent prices or fills. If a price or balance looks stale or missing, add a snapshot warning instead of guessing.
- Redact credential-like strings in logs, reports, and UI state.
- Keep syncs idempotent —
scripts/sync_webull.mjsupserts byaccount_id/position_idso repeated runs never duplicate rows.