stocktop

A top-like terminal tool that shows real-time stock prices and refreshes them on an interval.

Usage

stocktop [<code> ...]

• code — either an explicit market prefix + number, or a bare number with the market auto-detected:
  • sz<num> Shenzhen (China A-shares), e.g. sz300123
  • sh<num> Shanghai (China A-shares), e.g. sh600236
  • bj<num> Beijing (BSE), e.g. bj430047
  • hk<num> Hong Kong, e.g. hk01164
  • us<ticker> US, e.g. usAAPL

Auto-detection of bare codes

You can omit the sz/sh/hk prefix and the tool figures out the market from the number:

Pattern	Market	Examples
6-digit starting 60, 688, 689, or 5	Shanghai	600236, 688981, 510300
6-digit starting 000/001/002/003, 30, or 1	Shenzhen	000001, 002065, 300750, 159915
6-digit starting 43, 83, 87, 88, or 920	Beijing (BSE)	430047, 831010, 920019
5 digits or fewer	Hong Kong (zero-padded to 5)	700 → hk00700, 9988, 01164
letters (optionally with ./-)	US (uppercased)	aapl → usAAPL, TSLA, BRK.B

So stocktop 600236 700 AAPL is equivalent to stocktop sh600236 hk00700 usAAPL. Bare codes are stored in their canonical prefixed form in the cache. US tickers are case-insensitive on input but stored/queried uppercase (the data API is case-sensitive).

Codes that don't exist

If a code returns no data from the API (e.g. a typo or a delisted/nonexistent code), it is ignored — not shown as a table row — and a tip is printed below the table listing the ignored codes so you can fix or remove them.

Example

stocktop sz300123 sh600236 hk01164

Refresh interval

The interval is a persisted setting, not a command-line argument:

stocktop config interval 3     # refresh every 3 seconds (saved)
stocktop config interval       # show current interval
stocktop config                # show all config

It defaults to 5s until you set it, and is stored in ~/.config/stocktop/config.

Refreshes the quote table in place at the configured interval, like top — the table is redrawn at the same spot rather than scrolling. Red ▲ = up, green ▼ = down (Chinese-market convention). Press Ctrl-C to quit.

When output is piped or redirected (not a terminal), it falls back to printing a new block each cycle so logs stay readable.

Caching

The code list is cached to ~/.config/stocktop/codes between runs:

• No codes given → shows last run's cached list. e.g. stocktop or stocktop 3.
• Bare codes → moved to the top of the list (deduped). The new list always wins on ordering: a code already cached is moved up to its new position, then the remaining cached codes follow.
• -code (minus prefix) → removes that code from the cached list.

So if the cache is sz300123 sh600236 hk01164 and you run stocktop hk01164 sz000001, the result is hk01164 sz000001 sz300123 sh600236 — new codes first.

Sorting (live)

While running, press a key to sort the table by a column. Clicking headers isn't used — terminals don't deliver mouse clicks to programs reliably — so it works htop-style with keys instead:

Key	Sorts by
c	code
n	name
p	price
g	change %
l	original list order
q	quit

Pressing the same key again reverses the direction. The active column is marked in the header with ↑/↓. Sorting is instant (no extra network fetch), and codes with no data sink to the bottom.

Managing the list

stocktop -sh600236            # remove sh600236
stocktop hk00700 -sz300123    # add one and remove one in the same run
stocktop list                 # print the cached codes and exit
stocktop clear                # wipe the whole cached list

Removing the last remaining code empties the cache and exits cleanly.

Market hours

The tool only polls markets that are currently open. Each refresh, it checks the live trading session for every market in your list and skips the network call for any that are closed — closed stocks keep showing their last fetched price.

Market	Session (local time)
China A-shares (sh/sz/bj)	09:30–11:30, 13:00–15:00 CST
Hong Kong (hk)	09:30–12:00, 13:00–16:00 HKT
US (us)	09:30–16:00 ET

Markets are also treated as closed on weekends and public holidays. The holiday calendar is fetched once from Nager.Date (keyless) and cached to ~/.config/stocktop/holidays-<COUNTRY>-<YEAR>. The header shows an open (●) / closed (○) indicator per market. If every market in your list is closed, no network requests are made at all.

Note: mainland-China makeup workdays (调休 weekends) aren't accounted for, so on those rare days a closed CN market won't auto-refresh.

Data sources

Quotes come from multiple keyless sources, chosen per market with automatic fallback:

Market	Source priority
China (sh / sz / bj / hk)	Tencent → Sina → Eastmoney
US	Yahoo Finance → Tencent → Sina → Eastmoney

Each market group is fetched from its preferred source; any codes still missing are retried against the next source in the chain. The header shows which source(s) supplied the data (e.g. tencent+yahoo). No API key required.

• Tencent qt.gtimg.cn — sh/sz/bj/hk/us
• Sina hq.sinajs.cn — sh/sz/bj/hk
• Eastmoney push2.eastmoney.com — sh/sz/hk/us (one request per code)
• Yahoo query1.finance.yahoo.com — US (primary), HK

Build & run

Requires Swift (comes with Xcode Command Line Tools on macOS: xcode-select --install).

cd stocktop
swift build -c release
.build/release/stocktop sz300123 sh600236 hk01164

To install on your PATH:

cp .build/release/stocktop /usr/local/bin/