Overview · Whale Docs

WhaleCore is a UI-free securities data SDK. Broker App implements its own interface and uses WhaleCore for client sessions, real-time data, and business services; capabilities the typed services do not cover yet are called through WhaleCore’s requestService() against TradingAPI. TradingAPI is reachable only through WhaleCore — a Broker App or Broker Server that calls it directly fails.

Note

This documentation is derived from public interfaces in the WhaleCore iOS and Android source. Artifact locations, version compatibility, project credentials, and environments are supplied by the Whale project team.

When to use it

Fully custom UI

Broker designs every securities screen and interaction instead of using WhaleAppSDK UI.

Reusable client foundations

The SDK manages sessions, auth recovery, WebSockets, caching, and business data services.

Public capabilities

Module	iOS	Android	Capability
Quotes	`quoteService()`	`getQuoteService()`	Real-time quote subscriptions (four entry points: single-instrument detail, instrument list (excluding options), option list, and option chain; batch entry points support whole-set replacement), K-lines and timeshares (the latest bar / point updates in real time from quote pushes), historical trades, and quote level with device eviction
Option calculator	`WhaleCoreOptionCalculator` (static utility)	`OptionCalculator` (static utility)	Local Black-Scholes calculations: Greeks, theoretical price, intrinsic/time value, days to expiry, and probability of profit
Warrant calculator	`WhaleCoreWarrantCalculator` (static utility)	`WarrantCalculator` (static utility)	Local calculation of Hong Kong warrant metrics: premium, gearing, effective gearing, break-even point, moneyness, distance to call price, conversion price, and delta
Orders	`orderService()`	`getOrderService()`	Submit, replace, cancel, attached orders, take-profit/stop-loss on a position, order preview, estimates, pre-trade validation, trade card selection, and order events
Portfolio	`portfolioService()`	`getPortfolioService()`	Portfolio subscriptions, cash details, member portfolio settings, and profit-and-loss analysis (cross-currency conversion happens inside the SDK; neither platform exposes an exchange-rate lookup API)
Watchlist	`watchlistService()`	`getWatchlistService()`	Group and stock CRUD, ordering, pinning, invalid-ticker cleanup, and events
Requests	`requestService()`	`getRequestService()`	The only call path to TradingAPI; adds common parameters and auth headers, and recovers and retries on auth expiry
Trade tokens	`updateTradeToken(_:...)` / `hasTradeToken()`	`updateTradeToken()` / `hasTradeToken()`	Needed only in trade-password verification mode (`tradePasswordEnabled` at initialization): Broker App verifies the trading password and supplies the trade token. In the default mode the SDK obtains and renews it automatically

Note

For pre-trade validation, call the same-named methods on orderService() / getOrderService(). The legacy standalone entry point WhaleCoreService.orderValidationService (iOS) is deprecated but still available; WhaleCore.getOrderValidationService() (Android) has been removed. The Android portfolio entry point getPortfoliosService() has been renamed to getPortfolioService().

SDK instrument identifiers use the CounterId form, such as ST/US/AAPL or ST/HK/00700.

Integration model

flowchart LR
    A[Broker App UI] --> B[WhaleCore]
    B --> C[WebSocket connections]
    B --> D[Quotes / orders / portfolio / watchlists]
    B --> E[Automatic token renewal]
    B --> F[requestService]
    F --> G[TradingAPI HTTP]

Startup flow

sequenceDiagram
    participant A as Broker App
    participant B as WhaleCore
    participant C as Broker Server
    participant D as Whale Server

    activate A
    A->>C: Request a Whale member token
    activate C
    C->>D: POST /v1/whaleapi/auth/open_id/login
    activate D
    D-->>C: member token/refreshToken
    deactivate D
    C-->>A: member token/refreshToken
    deactivate C

    A->>B: initialize(config)
    activate B
    B->>D: Validate token
    activate D
    D-->>B: Valid/invalid
    deactivate D
    B-->>A: Start succeeds/fails
    deactivate B
    deactivate A

Platforms

Platform	Status	Guide
iOS	Available; iOS 13+; Swift / Objective-C	iOS
Android	Available; Kotlin / Java	Android
Web	Available; WebAssembly in the browser; TypeScript	TypeScript
Flutter	Available; Android and iOS; Dart	Flutter