Android

Apply the whalecore.gradle script that ships with the delivery in the target module’s build.gradle[.kts]:

// Kotlin DSL
apply(from = "<path-to>/whalecore/whalecore.gradle")

// Groovy DSL
apply from: "<path-to>/whalecore/whalecore.gradle"

whalecore.gradle automatically injects into the module:

• Every local AAR under whalecore/libs/ (the SDK itself and its dependencies)
• The remote transitive dependencies the SDK needs at runtime (lifecycle-runtime, datastore-preferences, jackson-kotlin, protobuf-kotlin-lite, moshi-kotlin, jna)
• The coreLibraryDesugaring configuration required when minSdk < 26

The host still configures minSdk, JVM target, and the Kotlin plugin itself. See example/app/build.gradle.kts for a complete integration example.

Delivery directory layout:

WhaleCore-Android-<version>/
├── README.md                          Documentation
├── CHANGELOG.md                       Public interface change log
├── whalecore/
│   ├── libs/                          Local AARs for the SDK and its dependencies
│   └── whalecore.gradle               One-line integration script
└── example/                           A self-contained sample project that already applies whalecore.gradle

example/ demonstrates the full integration flow. Run it before integrating into your own project:

cd example
./gradlew :app:installDebug

You can also open example/ directly in Android Studio.

Call WhaleCore.initialize before using any service. It is blocking (it performs network requests), so run it on an IO thread. Call it in Application.onCreate or before the first protected screen.

val config = WhaleCoreConfig(
    appId = "<assigned>",
    appKey = "<assigned>",
    appSecret = "<assigned>",
    token = accessToken,
    refreshToken = refreshToken,
    defaultAccountChannel = "lb_hk",
    deviceId = deviceId,
    language = WhaleCoreLanguage.EN,
    logLevel = WhaleCoreLogLevel.INFO,
    tokenRefreshCallback = appTokenRefreshCallback,
)

withContext(Dispatchers.IO) {
    WhaleCore.initialize(application, config, isDebug = BuildConfig.DEBUG)
}

Common WhaleCoreConfig fields:

Key points:

• Repeated calls are safe; only the first takes effect. Concurrent calls block until the first initialization completes.
• Initialization validates required fields first and throws WhaleCoreException.InvalidParameter when a field is missing (or deviceId is shorter than 32 characters); parameterName identifies the offending field.
• Query the status with WhaleCore.isInitialized().
• Never log the whole config; it contains sensitive credentials such as appSecret and token.

WhaleCore.resume() and WhaleCore.pause() describe the whole application moving between foreground and background — call each once per transition. Forwarding them from ProcessLifecycleOwner in your Application class is the recommended approach:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        ProcessLifecycleOwner.get().lifecycle.addObserver(object : DefaultLifecycleObserver {
            override fun onStart(owner: LifecycleOwner) = WhaleCore.resume()
            override fun onStop(owner: LifecycleOwner) = WhaleCore.pause()
        })
    }
}

Do not hook them to a single Activity’s onResume / onPause — navigating between screens fires those too, which would falsely report “went to background” to the SDK. Both are safe no-ops before initialization.

Sign out, tear down, or switch accounts with:

withContext(Dispatchers.IO) { WhaleCore.logoutAndDestroy() }

logoutAndDestroy() first notifies the server that the current session is invalid, then releases every resource the session held (network connections, caches, and native handles). It is blocking: by the time it returns, both sign-out and resource release have finished. Sign-out waits only up to a limit and its failure does not block resource release, so the method does not return a sign-out result. After teardown the SDK returns to the uninitialized state; calling initialize again with a new account’s config completes an account switch.

The SDK renews the access token automatically with refreshToken, so the host does not need to handle routine refresh. To keep the session usable, register a TokenRefreshCallback through config.tokenRefreshCallback (every method is called on the main thread and has a default implementation):

val appTokenRefreshCallback = object : TokenRefreshCallback {

    override fun onTokenRefreshed(token: String, refreshToken: String) {
        // New token / refreshToken. Whether and how to persist them is up to the host.
        credentialStore.update(token, refreshToken)
    }

    override fun resolveExpiredToken(callback: NewTokenCallback) {
        appScope.launch {
            val fresh = runCatching { authApi.silentLogin() }.getOrNull()
            // Supplying non-empty credentials lets the SDK retry the failed requests automatically.
            // Supplying empty values, or timing out, fails those requests; guide the user to sign in again.
            callback.onResult(fresh?.token.orEmpty(), fresh?.refreshToken.orEmpty())
        }
    }

    override fun onTokenRefreshFailed(exception: WhaleCoreException) {
        // Final notification that even the fallback retrieval failed: guide the user to sign in again.
        sessionRouter.gotoLogin()
    }
}

• Refresh succeeds (onTokenRefreshed): the SDK notifies the host that the token and refresh token changed.
• Session expires (resolveExpiredToken): the SDK gives the host one chance to fetch a fresh token; requests in flight suspend until it resolves. Multiple requests failing at once trigger this callback only once, and they share the result.
• Final failure (onTokenRefreshFailed): fired when the retry also failed to supply a valid token — normally the point at which you guide the user to sign in again.
• Call callback.onResult(...) within the timeout (tokenResolverTimeout, 30 seconds by default); not calling it in time counts as failure.
• The SDK holds this callback for the whole session. Pass an app-level singleton to avoid leaking an Activity or Fragment.

The following rules apply across services. Read them once; later sections do not repeat them.

A three-part format, ST/MARKET/CODE, such as "ST/US/AAPL" or "ST/HK/00700". Options additionally encode the strike price, expiry date, and direction. Quotes, orders, the watchlist, and profit-and-loss analysis all locate instruments with this format.

Every capability offers a coroutine suspend fun and a callback-based *Async(..., AsyncCallback<T>?) variant; choose whichever fits the call site (Java callers, or contexts where coroutines are inconvenient, use the callback variant). Method tables in this document list only the coroutine signature; the callback variant adds the Async suffix and keeps the same parameters.

// Coroutine variant
val stock = WhaleCore.getQuoteService().getStock("ST/US/AAPL")

// Callback variant
WhaleCore.getQuoteService().getStockAsync("ST/US/AAPL", object : AsyncCallback<Stock> {
    override fun onSuccess(result: Stock?) { /* ... */ }
    override fun onError(error: Throwable) { /* ... */ }
})

*Async calls and observation callbacks all fire on a non-main thread; switch back to the main thread before updating UI. A cancelled coroutine task (for example, after the session is destroyed) triggers no callback and never calls onError either. OptionCalculator is the exception: it is purely synchronous, involves no coroutines, and has no *Async variant.

Order, portfolio, watchlist, and quote push events all expose the same three consumption forms; choose the one that fits the call site:

SharedFlow defaults to replay = 0: events that happen before you register a listener are not replayed. Always register the listener before triggering a refresh or subscription.

Do not cache the instance returned by getXxxService() for long — it becomes invalid after logoutAndDestroy(), so fetch it again each time you need it. getXxxService() throws WhaleCoreException.NotReady before initialization or after teardown.

Trading requires a trade token, which the SDK obtains and renews automatically by default; the host does not participate and needs no configuration. If a trading-scoped call (submit, replace, cancel, and similar) fails with WhaleCoreException.TradeAuthFailed, that is a rare server-side auth failure — handle it through the common error handling path.

Getting a service before initialization throws WhaleCoreException.NotReady. OptionCalculator is a stateless utility class you call directly, not through WhaleCore; see Option calculator.

Fetch a snapshot, or use subscribe to open a live subscription that keeps delivering updates:

val quotes = WhaleCore.getQuoteService()

// Snapshot: fetch once
val stock = quotes.getStock("ST/US/AAPL")

// Live subscription: subscribe() opens it, chain the channels you need, then start(); onChange keeps delivering the latest quote
val subscription = quotes.subscribe(
    counterIds = listOf("ST/US/AAPL", "ST/HK/00700"),
    callback = object : QuoteEventCallback {
        override fun onChange(stock: Stock) { updateRow(stock) }
    },
).detail().depth().trade().start()

subscription.cancel()   // Cancel when the screen is destroyed

If the quote is already subscribed through another path, such as WatchlistService, use observeQuoteEvents(...) to observe the quote stream without opening a duplicate subscription.

val klines = quotes.getKlines("ST/US/AAPL", KlineType.PER_DAY, count = 200)

// A K-line update event requires an existing quote subscription for that instrument (even just .list()); the event
// only identifies which instrument changed, so fetch the latest series again with getKlines
lifecycleScope.launch {
    quotes.observeKlineUpdates(listOf("ST/US/AAPL")).collect { update ->
        val latest = quotes.getKlines(update.counterId, KlineType.PER_DAY, count = 200)
        // Redraw the K-line chart
    }
}

Use this endpoint for an intraday price chart; do not approximate it with 1-minute K-lines. Timeshares are grouped by trading day and carry the previous close and a running average price, while K-lines are a continuous series counted back from an anchor. On markets with few bars per day, such as Hong Kong or A-shares, approximating timeshares with K-lines mixes in data from the previous trading day.

val today = quotes.getTimeshares("ST/US/AAPL").timeshares.lastOrNull()
today?.minutes?.forEach { minute -> /* price via minute.price, average via minute.avgPrice */ }

Choose either a single-contract detail subscription or a batch chain subscription:

// Option detail subscription: single-contract snapshot + subscription, chain the data types you need
val optionSub = quotes.subscribeOptionDetail("OP/US/AAPL240119C190000", callback)
    .detail().depth().trade().start()

// Option chain subscription: a whole set of contracts, replaced wholesale on interaction (switching expiry, scrolling
// the visible range); no chained type selection needed
val chainSub = quotes.subscribeOptionChain(visibleCounterIds, callback)
chainSub.updateCounterIds(newVisibleCounterIds)   // Wholesale replacement, not incremental; hold a strong reference to the handle
chainSub.cancel()

Options have no separate depth-subscription channel: the snapshot from start() carries one level of depth, but subsequent pushes still need an explicit .depth() in the chain — without it, only the first frame carries depth. Greeks are not part of the quote push; subscribe to the underlying separately, take its price, and pass it to OptionCalculator for local computation.

When the same account uses premium quotes on multiple devices, those devices evict one another, and the evicted market is downgraded to a lower quote level.

// Read the current state synchronously; returns null until the first quote-entitlement check completes
val level = quotes.getQuoteLevelInfo()
if (level?.isMarketEvicted("US") == true) {
    // When evicted but the server returned no message, evictedDescribe is null or an empty string
    level.evictedDescribe?.takeIf { it.isNotEmpty() }?.let { showBanner(it) }
}

// Observe refreshes: the current snapshot arrives on subscription, and once per new quote-entitlement
// result thereafter (eviction, reclaim, or a language change)
lifecycleScope.launch {
    quotes.observeQuoteLevel().collect { info -> renderBanner(info) }
}

// "Restart quotes": take the entitlement back to this device. The state is not yet refreshed when this
// returns — dismiss the banner based on the subsequent callback
quotes.reclaimQuoteAccess()

Per-sub-market level detail lives in QuoteLevelInfo.subMarketQuote: the raw level identifier, the price level (priceLevel, with the convenience property isDelayed), depth levels by type (depthLevel, one entry per depthType; use maxDepthLevel for a coarse check), and flags for trades, broker queue, overnight, and pre/post-market. After a reclaim, the latest quotes for already-subscribed counters refresh automatically and pushes resume, but the tick-by-tick records from the evicted window are not backfilled — screens that need the complete sequence should call getTrades again after receiving a new, non-evicted snapshot. Banner presentation and policies such as “don’t show again today” are up to the host.

Method overview:

Chained type-selection methods on the subscription builders returned by subscribe / subscribeOptionDetail: list(), detail(), depth(), trade(), preTrade(), postTrade(); subscribe also offers broker(), nightTrade(), totalView(), and totalViewBrief() (the option data path does not support these four). Both builders support calling start() with no type selected at all, which fetches one snapshot and opens no push subscription — useful as a one-off snapshot call. The QuoteSubscription returned by start() has only cancel(); OptionChainSubscription additionally has updateCounterIds(counterIds) and an isCancelled property.

OptionCalculator is a stateless, pure computation utility (it is not registered on any service, performs no network calls, and has no *Async variant); the caller supplies all input, and it prices European options with Black-Scholes. In a quote context, take the underlying price from your own underlying subscription, and take implied volatility, strike price, days to expiry, and dividend from the option push.

val optionData = stock.extraData as ExtraData.OptionData
val underlyingPrice = underlyingStock.trading.lastDone ?: return

// Do not use optionData.dayToExpire directly (it counts trading days).
// Use fractionalDaysToExpire() for calculation input (fractional days, matching the official
// client's option calculator); use daysToExpire() (whole calendar days) for "N days left" displays
val days = OptionCalculator.fractionalDaysToExpire(optionData.expireDate, TimeZone.getTimeZone("America/New_York"))
    ?: return  // Invalid expiry date format

val input = OptionPricingInput(
    underlyingPrice = underlyingPrice,
    strikePrice = optionData.strikePrice ?: return,
    impliedVolatility = optionData.impliedVolatility ?: return,
    daysToExpire = days,
    isCall = OptionDirection.fromQuoteDirection(optionData.direction) == OptionDirection.CALL,
    dividendToExpire = optionData.dividendToExpire,
    // Leave interestRate unset to use the SDK's built-in rate (same source as QuoteService.getInterestRate())
)

val greeks = OptionCalculator.greeks(input)  // Returns null on invalid input; show a placeholder in the UI

Method overview:

val orders = WhaleCore.getOrderService()

orders.observeOrderEvents(this, object : OrderEventCallback {
    override fun onChange(order: Order) { updateOrder(order) }   // Delivers the latest snapshot on every change
})

The recommended flow validates before submitting: express the intent with OrderIntent, run validateOrder for full pre-submit validation, and submit the SDK-completed request directly once it passes — no need to assemble SubmitOrderRequest by hand.

// 1. Build the order intent: a limit buy of 100 shares of AAPL at 180.00
val intent = OrderIntent(
    counterId = "ST/US/AAPL",
    action = OrderAction.BUY,
    orderType = OrderType.LO,
).apply {
    price = "180.00"
    quantity = "100"
}

// 2. Run full pre-submit validation
val result = orders.validateOrder(intent, ValidationScope.Submission)
val request = result.request
if (request != null) {
    // 3. Validation passed; submit the SDK-completed request
    val submit = orders.submitOrder(request)   // submit.orderId is the order ID
} else {
    showIssues(result.issues)                  // Validation failed; issues list the reasons
}

You can also build a request directly with SubmitOrderRequest’s typed factory methods (market, if-touched, trailing stop, and so on), skipping the validation funnel. See Order types and attached orders for the full factory matrix.

An order can apply a commission-free card, a stock cash card, or a platform-fee card to discount the corresponding fee, passed through OrderIntent.cards (TradeCards). Validation, preview, and submission share the same value. The host fetches the card list itself; the SDK does not wrap a query endpoint. With no card selected, the submitted request’s card_ids is an empty array and the server redeems nothing, and the preview likewise computes without a card — to actually use a card, the host must place it explicitly in the matching slot.

intent.cards = TradeCards(
    // The amount is required: the preview computes discounted fees from it, and without it the
    // preview will not match what is actually charged
    commissionCard = TradeCard(cardId = "1001", availableAmount = BigDecimal("50"), rebateRate = BigDecimal("0.8")),
)

The three slots can also be read and written by category, so three card pickers can share one piece of UI logic:

val cards = intent.cards ?: TradeCards().also { intent.cards = it }
cards.setCard(TradeCardCategory.CASH, TradeCard(cardId = "2002", availableAmount = BigDecimal("100")))
cards.card(TradeCardCategory.CASH)      // Read that category back
cards.isEmpty                           // Whether all three slots are unselected

The server-configured default card is returned with the constraints snapshot, which is handy for marking the default selection in the card picker. The SDK does not fill it in automatically — whether to use it is the integrator’s decision:

val constraints = orderService.getOrderConstraints(counterId)
// A null slot means the server configured no card of that category for this counter,
// so disable that category's card picker
constraints.suggestedCard(TradeCardCategory.COMMISSION)?.let { suggested ->
    suggested.cardType                                  // The card-type argument for querying that category's card list
    cards.setCard(TradeCardCategory.COMMISSION, suggested.toTradeCard())  // null when the amount is missing; nothing is pre-filled
}

val today = orders.getTodayOrders()
val history = orders.getHistoryOrders(HistoryOrdersRequest(page = 1, limit = 20))
val detail = orders.getOrderDetail(orderId)

orders.cancelOrder(orderId)

// Replace: change only the price (quantity is required — resend the original quantity even when you are not changing it)
orders.replaceOrder(ReplaceOrderRequest.regular(orderId = orderId, quantity = "100", price = "182.00"))

Replacing conditional orders (LIT/MIT/TSL) and option orders uses their own factory methods; see Order types and attached orders.

Batch cancellation:

orders.batchCancelOrders(counterId = "ST/US/AAPL")   // Cancel by instrument (omit action for both directions)
orders.batchCancelOrdersByIds(listOf("1", "2", "3"))

// Recommended: one call returns the trade capacity snapshot for an entire order screen
val capacity = orders.getTradeCapacity(
    TradeCapacityRequest(counterId = "ST/US/AAPL", action = OrderAction.SELL,
        submitPrice = "180.5", orderType = OrderType.LO, settlementCurrency = "USD")
)
val sellable = capacity.sellableQuantity        // Sellable from holdings
val shortable = capacity.shortSellableQuantity  // Sellable short

See the method overview below for the maximum buy limit (stocks only, getEstimateBuyLimit), position detail (getTradeDetail), and order info (getOrderInfo).

A black-box validation capability: the host passes only the order intent, and the SDK manages data fetching and caching internally. Every issue means the order would fail if submitted as-is, with no warning level; a business failure never throws — it is always returned through issues.

// 1. Before entering the order screen
val entry = orders.checkTradability("ST/HK/00700")
if (!entry.passed) { showBlocked(entry.issues.first().reason); return }

// 2. Render the constraint snapshot when the order screen opens
val constraints = orders.getOrderConstraints("ST/HK/00700")
renderOrderTypes(constraints.supportedOrderTypes)

// 3. While editing: lightweight per-field validation drives button and field states
val draft = orders.validateOrder(intent, ValidationScope.Draft)
submitButton.isEnabled = draft.passed

// 4. Full pre-submit validation; on success, submit the resulting request (see "Build and submit an order")

Qualification states (for example, the US overnight-trading disclosure or a W-8BEN) are queried and resolved through getQualifications(counterId), which returns the full set — each item has type, state, expired, and acceptableViaApi. Branch on acceptableViaApi first:

val qualifications = orders.getQualifications("ST/US/AAPL")
val unresolved = qualifications.firstOrNull { !it.isSatisfied }
if (unresolved != null && unresolved.acceptableViaApi) {
    orders.acceptAgreement(unresolved.type)   // The SDK invalidates its cache after acceptance; re-run validation to see the new state
}

Items with acceptableViaApi == true — disclosure and entitlement items such as US overnight trading, options overnight trading, odd lots, US short selling, penny stocks, OTC trading, warrants and CBBCs, CAR-CKA, and virtual-asset ETF assessment and additional risk disclosure, plus the options risk agreement and the listed-derivatives ETF assessment — can be accepted in one call with acceptAgreement(type), or, for the assessment only, answered with submitListedDerivAssessment(experience) (choosing DerivExperience.NONE records a failed assessment and keeps the block in place). The virtual-asset ETF assessment and its additional risk disclosure share a single signature: accepting either one sets both server-side, so present both to the user and obtain confirmation before calling. Items with acceptableViaApi == false — assessment or certification items such as PI, VA, W-8BEN, and Hong Kong margin short selling — must be handled with the broker directly; the SDK exposes no handling link, and calling acceptAgreement on one of these throws IllegalArgumentException (a programming error, not one of the WhaleCoreException types). Both methods invalidate the internal qualification cache on success, so re-running validation picks up the new state.

// Shares the same OrderIntent as validation and submission; preview at any point while editing
val context = OrderPreviewContext().apply {
    marketReferencePrice = BigDecimal("180.00")   // Required for market orders or when there is no submit price; otherwise amount fields are null
    // Option instruments must pass optionDirection, or the call throws WhaleCoreException.InvalidParameter
}
val preview = orders.previewOrder(intent, context)

preview.orderAmount        // Estimated order amount
preview.fees.total         // Estimated total fees (after discount)
preview.orderTotal         // Estimated order total
preview.riskHint           // Risk hint, such as FINANCING_NEEDED (financing will be used)

A synchronous, pure-computation entry point, OrderPreviewCalculator.compute(fields), is also available for hosts that fetch data themselves; it shares the same computation as previewOrder.

Places a take-profit and a stop-loss conditional order in one call against a position you already hold. This differs from an attached order: an attached order rides on a newly submitted parent order and activates only after that order fills, while TPSL acts directly on an existing position and needs no parent order. The caller does not specify a direction; the SDK derives it from whether the position is long or short.

val tpslIntent = TPSLOrderIntent("ST/US/AAPL").apply {
    quantity = "100"
    wantsTakeProfit = true
    takeProfitTriggerPrice = "200.00"
    wantsStopLoss = true
    stopLossTriggerPrice = "160.00"
}
submitBtn.isEnabled = orders.validateTPSLOrder(tpslIntent, ValidationScope.Draft).passed

val tpslResult = orders.validateTPSLOrder(tpslIntent, ValidationScope.Submission)
if (tpslResult.passed) {
    val placed = orders.submitTPSLOrder(tpslResult.request!!)
    // placed.ployId is shared by both orders; placed.orders lists each leg's ployType (TAKE_PROFIT/STOP_LOSS) and orderId
}

Replace and cancel go through the regular endpoints, not this one: a placed TPSL order is an ordinary conditional order, so replace it with replaceOrder and cancel it with cancelOrder.

SubmitOrderRequest can only be built through its companion-object factories:

OrderType.TS (trailing stop market) is entirely unsupported — the enum constant exists, but there is no submit or replace factory for it, and pre-submit validation blocks it with ORDER_TYPE_NOT_SUPPORTED (1109).

ReplaceOrderRequest follows the same pattern with companion-object factories: regular (a plain stock order), option (an option parent order, which always carries the required price and quantity), and limitIfTouched / marketIfTouched / trailingStopLimit (conditional orders, which take triggerStatus and isOption — only an already-triggered order routes to the plain/option parent-order endpoint, and everything else uses the conditional-order endpoint).

Attached-order (AttachedParams) factories: takeProfit, stopLoss, bracket, and cancelAll (used only when replacing an order, to cancel all its attached orders). Activation methods: AttachedActivation.marketIfTouched(rth) and limitIfTouched(profitTakerSubmitPrice?, stopLossSubmitPrice?, rth). Price validity constraints: for a buy parent order, takeProfitPrice > current price > stopLossPrice (reversed for a sell); attached orders cannot be included when forceOnlyRth = OVERNIGHT.

// A bracket order
val withAttached = SubmitOrderRequest.limit(common, price = "350.00").attaching(
    AttachedParams.bracket(
        takeProfitPrice = "360", stopLossPrice = "340",
        activation = AttachedActivation.marketIfTouched(),
    )
)

// Replace the parent order and cancel all its attached orders
service.replaceOrder(
    ReplaceOrderRequest.regular(orderId = "123", quantity = "50")
        .attaching(AttachedParams.cancelAll())
)

// Change a single attached order's trigger price without touching the parent order; a LIT-activated attached
// order's submit price must be resent even when it is not changing
service.replaceAttachedOrder(
    ReplaceAttachedOrderRequest.modifyProfitTaker(
        mainId = "123", mainQuantity = "100", marketPrice = "355",
        profitTakerId = "999", newPrice = "365",
    ),
)

Single-leg option orders reuse the same factories for submit and replace, with no option-specific parameters — the SDK routes to the option-specific endpoint automatically when counterId is an option contract. The option channel does not return an attached-order allowlist, so selecting take-profit or stop-loss is blocked with 1608.

When you build SubmitOrderRequest directly through the factories, pass cards through OrderCommon.cardIds (submission only needs the card IDs; the balance and discount rate are needed only on the OrderIntent.cards path used for validation and preview). The three card slots always appear in a fixed order: commission-free card, cash card, platform-fee card.

Method overview:

A standalone utility, OrderPreviewCalculator.compute(fields) (synchronous pure computation), is also available; see Order preview.

val portfolios = WhaleCore.getPortfoliosService()

// Register the listener before subscribing to accounts, so you don't miss the first frame
portfolios.observePortfolioEvents(this, object : PortfolioEventCallback {
    override fun onMessage(accountInfo: AccountInfo, portfolio: Portfolio) { render(portfolio) }
    override fun onFailure(accountInfo: AccountInfo?, error: Throwable) { showError(accountInfo, error) }
})

portfolios.setSubscribedAccounts(listOf("lb"), "HKD")  // Subscribes every opened account (including sub-accounts) under the channel
portfolios.refresh()   // Refresh once when entering the screen

Cash detail and position-quote linkage toggles: enableCashDetail(enabled) / isEnableCashDetail(), enableQuotes(enabled) / isEnableQuotes().

Read, modify, and submit; a successful update triggers a refresh automatically:

val setting = portfolios.getPortfolioMemberSetting()
portfolios.updatePortfolioMemberSetting(
    setting.copy(costType = PortfolioCostType.AVG, showDelistedHoldings = true)
)

Business-level aggregation APIs for account-level, per-stock, and per-market profit-and-loss analysis, one method per UI panel:

val meta = portfolios.getProfitLossAnalysisMeta()      // Time-filter bounds + optional comparison indexes
val overview = portfolios.getProfitOverview("HKD", PLPeriod.allTime)
val trend = portfolios.getProfitTrend(
    currency = "HKD",
    period = PLPeriod.allTime,
    indexCounterId = meta.indexes.firstOrNull()?.counterId,  // Pass null to skip index comparison
)
renderTrendChart(trend.selfSeries, trend.indexSeries)  // Both series are equal length and index-aligned; plot them directly

Models mirror the server response: amounts, ratios, and timestamps are always raw strings; non-business nullable fields default to an empty value (empty string / 0 / false).

Core method overview (subscription/settings; see the table above for profit-and-loss analysis methods):

val watchlist = WhaleCore.getWatchlistService()

// Register the listener before triggering a data change — SharedFlow defaults to replay=0 and does not replay
// events from before you subscribed
lifecycleScope.launch {
    watchlist.observeWatchlistEvents().collect { event ->
        when (event) {
            is WatchlistEvent.Groups -> renderGroups(event.groups, event.stockInfo, event.ties)
            is WatchlistEvent.SortGroups -> applySort(event.sortGroups)
            else -> Unit
        }
    }
}
watchlist.refresh(sub = true)

// Add, move across groups, remove
watchlist.addStocks(counters = listOf("ST/US/AAPL"), groups = listOf(groupId), removeGroups = emptyList())
watchlist.removeStocks(counters = listOf("ST/US/NVDA"), groups = listOf(groupId), removeAll = false)

Fund and note data do not live on WatchlistStock; fetch them through their own events instead — funds through WatchlistEvent.Funds, and notes through WatchlistEvent.Notes (Map<counterId, note>).

val groupId = watchlist.addGroup("Tech stocks")
watchlist.renameGroup(groupId, "US tech")
watchlist.sortGroups(listOf(groupId, otherGroupId))   // Pass every group ID in the target order

watchlist.tie(listOf("ST/US/AAPL"))
watchlist.sortTied(listOf("ST/US/AAPL", "ST/HK/00700"))

// Sort the current group intelligently by market open time
watchlist.setGroup(groupId = groupId, sortMode = "US|HK,SG,CN", asc = true)

Method overview:

Use WhaleCore.getRequestService() to call TradingAPI endpoints that do not yet have a typed WhaleCore service. Take the endpoint path, parameters, and response schema from the TradingAPI documentation. The host supplies those request values; WhaleCore adds the common parameters and headers for signing, authentication, and tracing. If login or trade authentication expires, the SDK recovers it and retries once.

HttpRequest is immutable and accepts:

send returns an HttpResponse containing the raw JSON bodyString and response headers. Parse the body with the JSON library used by the host app.

import longbridge.whalecore.business.request.model.HttpMethod
import longbridge.whalecore.business.request.model.HttpRequest

val request = HttpRequest(
    method = HttpMethod.GET,
    path = "/v2/member/info",
    query = mapOf("include_accounts" to true)
)

val response = WhaleCore.getRequestService().send(request)
val member = json.decodeFromString<MemberInfo>(response.bodyString)
println(member.name)

For an endpoint that requires trade authentication:

val request = HttpRequest(
    method = HttpMethod.GET,
    path = "/v5/orders/today",
    requiresTradeToken = true
)

val response = WhaleCore.getRequestService().send(request)
println(response.bodyString)

Java callers can use sendAsync(request, callback) instead of the suspending send method.

See each type’s KDoc for the complete field reference in your IDE.

Every public API fails through a subtype of WhaleCoreException, so the host can branch on it:

try {
    val stock = WhaleCore.getQuoteService().getStock("ST/US/AAPL")
} catch (e: WhaleCoreException.NetworkUnavailable) {
    // Show a network hint and retry
} catch (e: WhaleCoreException) {
    showToast(e.message)   // message is already localized to language; show it directly
}

• Get the SDK version at runtime with WhaleCore.version (format 1.0.0(123)); the version name and build number are also available separately as WhaleCore.versionName / WhaleCore.versionCode.
• Check the initialization state with WhaleCore.isInitialized().
• Switch language at runtime with WhaleCore.setLanguage(...) (no re-initialization needed).