tickdb

Real-time market data and company fundamentals from the command line.

Covers forex, precious metals, indices, US/HK/A-shares, China/Hong Kong futures, and crypto via the TickDB unified API.

v0.2.1 covers 43 REST GET endpoints: 42 from the supplied 2026-09-21 API documentation snapshot plus the API key subscriptions endpoint supplied in a later screenshot, excluding the three full-market snapshot endpoints. Contract mapping and migration notes. Company fundamentals cover supported US, HK, and A-share stocks.

Install

npm install -g tickdb

Requires Node.js ≥ 18.

Quick Start

# 1. Get a free API key at https://tickdb.ai
# 2. Save it locally
tickdb config set-key YOUR_KEY

# 3. Start querying
tickdb ticker BTCUSDT
tickdb ticker BTCUSDT,XAUUSD,AAPL.US,700.HK

Commands

Market Data

| Command | Description | |---------|-------------| | tickdb ticker <symbols> | Real-time price snapshots | | tickdb kline <symbol> -i <interval> | Historical K-lines; --adjust none/forward/backward for CN/HK/US stocks | | tickdb kline-latest <symbols> -i <interval> | Live K-lines; also supports --adjust | | tickdb depth <symbol> | Order book (bids and asks) | | tickdb trades <symbol> | Recent executed trades | | tickdb symbols | List available symbols, including --type futures | | tickdb intervals | List documented K-line intervals offline |

Stock Data

| Command | Description | |---------|-------------| | tickdb ex-factors <symbols> | Stock adjustment factors; optional --from/--to in Unix milliseconds | | tickdb stock-info <symbols> | Stock names, share capital and per-share metrics; up to 500 symbols | | tickdb intraday <symbols> | Today's minute-by-minute price | | tickdb sessions [-m <market>] | Market-local trading sessions; omit market to return all markets | | tickdb trade-days -m <market> --from --to | YYYYMMDD dates; at most 31 days; start within the most recent year | | tickdb metrics <symbols> | Market metrics (PE, PB, market cap) | | tickdb capital-flow <symbol> | Capital flow analysis |

Company Fundamentals

All fundamentals commands are under tickdb finance.

| Command | Description | |---------|-------------| | finance profile <symbol> | Current company profile | | finance executives <symbol> | Current executives and directors | | finance financials-latest <symbol> --kind | Latest N financial reporting periods | | finance financials-annual <symbol> --kind | Latest N annual reports | | finance financials-ttm <symbol> --kind | Trailing-twelve-month financials | | finance financial-fields --kind | Bundled field dictionary, offline; availability varies by company/period | | finance segments-latest <symbol> | Latest business or regional segments | | finance segments-history <symbol> | Historical business or regional segments | | finance valuation-latest <symbol> | Current valuation snapshot | | finance valuation-history <symbol> | PE history; --granularity daily/monthly, optional --from/--to | | finance industry-peers <symbol> | Peer-company valuation cross-section | | finance industry-distribution <symbol> | Industry valuation distribution | | finance industries-rank --market | Market-level industry ranking | | finance industries-tree --market --industry-id | Industry hierarchy and chain | | finance dividends <symbol> | Dividend events; --dividend-type, dates, --limit, --cursor | | finance dividends-ttm <symbol> | Trailing-year cash dividends per share, by currency; optional --as-of | | finance buyback <symbol> | Buyback plans and events | | finance shareholders-latest <symbol> | Current shareholder structure | | finance shareholders-top <symbol> | Top-ten shareholder ranking | | finance shareholder-detail <symbol> --object-id | Detailed shareholder holdings | | finance fund-holdings <symbol> | Current fund holdings with pagination | | finance corp-actions <symbol> | Corporate action events | | finance news <symbol> | Company news list; includes news_id, not article bodies | | finance news-detail <news-id> | News body or available excerpt/status | | finance market-status | CN/HK/US trading status in one call | | finance calendar-report | Earnings/report events | | finance calendar-dividend | Dividend calendar | | finance calendar-split | Split/reverse-split events | | finance calendar-ipo | IPO offering/listing events | | finance calendar-other --category <category> | Other financial events | | finance calendar --category <category> | Compatibility router to the dedicated calendar endpoints |

Configuration

| Command | Description | |---------|-------------| | tickdb config set-key <key> | Save API key locally | | tickdb config show-key | Show stored key (masked) | | tickdb config clear-key | Remove stored key |

Common Options

These flags are supplied to the relevant command. --type choices vary by endpoint; fundamentals accept only stock. Offline intervals and finance financial-fields do not require an API key.

| Flag | Description | |------|-------------| | -k, --key <key> | Override API key for a single call | | -t, --type <type> | Asset type for disambiguation (stock, crypto, forex, futures, indices) | | -j, --json | Output raw JSON instead of formatted tables | | -V, --version | Show version | | -h, --help | Show help |

Examples

# Price snapshots — crypto, forex, stocks
tickdb ticker BTCUSDT,ETHUSDT
tickdb ticker XAUUSD,EURUSD
tickdb ticker AAPL.US,TSLA.US,700.HK

# Disambiguate symbols that exist in multiple markets
tickdb ticker 000070 -t stock
tickdb kline 000070 -i 1d -t stock

# K-line candles
tickdb kline BTCUSDT -i 1d --limit 10
tickdb kline XAUUSD -i 1h --limit 24

# Live candle
tickdb kline-latest BTCUSDT,XAUUSD -i 1h

# Order book
# API depth is market-dependent; -l only limits the local table
tickdb depth BTCUSDT -l 10

# Recent trades
tickdb trades 700.HK -l 20

# Discover symbols
tickdb symbols -t crypto -l 20
tickdb symbols -m US -l 10

# Stock fundamentals
tickdb stock-info AAPL.US,700.HK

# Intraday minute data
tickdb intraday AAPL.US

# Trading sessions & calendar
tickdb sessions -m US
tickdb trade-days -m HK --from 20260101 --to 20260131

# Market metrics
tickdb metrics AAPL.US,TSLA.US

# Capital flow
tickdb capital-flow 700.HK

# Company profile and executives
tickdb finance profile AAPL -t stock
tickdb finance executives 700 -t stock

# Financial statements: IS (income), BS (balance sheet), CF (cash flow)
tickdb finance financials-latest AAPL --kind IS -n 4
tickdb finance financials-annual 600519 --kind BS --years 5 -t stock
tickdb finance financials-ttm AAPL --kind CF --fields NetOperateCashFlow

# Valuation and industry data
tickdb finance valuation-history AAPL --granularity monthly --from 2025-01-01 --to 2026-09-21
tickdb finance industries-rank -m US -l 20

# Holders, news, and calendar
tickdb finance shareholders-top AAPL
tickdb finance news AAPL --from 2026-01-01 --to 2026-08-10
tickdb finance calendar-report --from 2026-09-21 --to 2026-09-28 -m US --limit 100

# Futures and adjusted prices
tickdb symbols -m HK -t futures
tickdb kline HSI8888 -i 1m -t futures
tickdb kline AAPL.US -i 1d --adjust forward
tickdb ex-factors AAPL.US,700.HK -t stock

# News details, dividend totals, and market status
tickdb finance news-detail 6288041
tickdb finance dividends-ttm AAPL --as-of 2026-09-21
tickdb finance market-status
tickdb finance calendar-other --category halt_resume -m CN

# Raw JSON output
tickdb ticker BTCUSDT --json
tickdb finance profile AAPL --json

Query and Output Semantics

• K-line intervals: 1m 3m 5m 15m 30m 1h 2h 4h 1d 1w 1M; lowercase m means minutes, uppercase M means months. The final historical candle may still be forming. Adjusted history may change after corporate actions; record retrieval time and adjust when archiving.
• Historical K-line --limit is passed through: the documented service caps values above 1000 and uses 100 for non-positive values. Recent trades default to 100, with a maximum of 1000.
• Depth is market-dependent: US stocks and China futures up to 1 level per side; HK stocks and HK futures up to 10; A-shares up to 5; crypto up to 1000. Actual available levels may be fewer. depth --limit truncates only the table, not the request or JSON.
• Snapshot fields are conditional. The *_24h fields generally represent a rolling 24-hour window for crypto and a trading day/session for traditional markets. Use --json for all fields, including extended-session quotes, share counts, and metadata. Missing optional fields are left blank.
• K-line tables show adjustment mode, turnover and futures open interest when present; trade tables show futures open-interest change and position effect.
• Financial --periods/--years count reporting periods, not rows. --fields now filters table rows locally by field_name; it is never sent to the API, and --json still returns the complete response. For cash flow, the documented operating-cash-flow field is NetOperateCashFlow.
• Valuation history is PE only. --metric PE remains accepted as a compatibility option but is not sent. Other metrics are rejected. Default history is one year for daily and five years for monthly; no matching business data returns 40405.
• dividends-ttm reports cash dividends per share, separated by currency; it does not report dividend yield.
• News published_at is an RFC 3339 timestamp. A news body may be unavailable for pending, blocked, or failed status. content_scope=excerpt means a partial excerpt; raw body_html is external content and must be sanitized by applications that render it.

Calendar and Pagination

Calendar commands accept --from, --to (inclusive YYYY-MM-DD dates), --market, --symbols (up to 50), --limit (1–500, default 100), and --cursor. The four dedicated report/dividend/split/IPO commands do not take --category.

calendar-other requires one category: macrodata, closed, meeting, merge, halt_resume, special_treatment, special_treatment_start, special_treatment_end, listing_status, listing_suspension, listing_resumption, delisting, or lockup_expiry.

When omitted, the start date is the current UTC date and the end date is seven days later. Market-restricted API keys must supply an allowed --market. Empty event arrays are successful results.

For calendars, dividends, and fund holdings, pass the previous response's page.next_cursor unchanged to retrieve the next page. Keep all other filters unchanged and stop when the cursor is null. If the first calendar request omitted dates, use its returned data.from and data.to for subsequent pages. The CLI makes one request per invocation; it does not automatically consume every page. Dividends default to 100 rows and fund holdings to 200; both allow up to 500.

Errors

The CLI checks both HTTP status and business code, supports numeric/string error codes, preserves the server message, and exits with status 1 on errors. It reports Retry-After when present and available asset types for AMBIGUOUS_SYMBOL. It does not automatically retry.

Hints cover authentication (1001, 1002, 1004, 1005), parameters (2001–2006, 2008), permissions/quotas (3001–3012), channel permissions (4005), service failures (5000–5006), and fundamentals (40001, 40101, 40404, 40405, 50001). Unknown codes are preserved; the client does not infer codes from message text. 2004 is an endpoint-specific request-count limit, not a universal 50-symbol limit. Invalid JSON and missing business codes are reported rather than silently displayed as success.

Observed production compatibility

The HTTP API can return code="Invalid or expired token" with HTTP 401. The CLI explicitly recognizes this exact code and adds API-key recovery guidance, while preserving the original code and message. It does not extract 1001 from message text.

A ticker query for an unavailable or unknown symbol can return HTTP 200, code=0, and data=[]. In table mode the CLI shows “No ticker data returned” and suggests checking symbols/type or using tickdb symbols. This successful empty result retains exit status 0; --json outputs the unchanged response. Empty data alone does not prove that a symbol is invalid. An actual server error 2002 still exits with status 1 and its documented hint.

These are compatibility rules based on live observations from 2026-09-21. They supplement the supplied API documentation; the CLI does not change the upstream HTTP status or business code.

API Key subscriptions

tickdb apikeys subscriptions
tickdb apikeys subscriptions --json

Calls GET /v1/apikeys/subscriptions with the usual X-API-Key authentication and no query parameters. The default output shows account/server metadata and each returned key's ID, prefix, name, plan, status, expiry, remaining seconds, and creation time. --json preserves the complete response. Values, including remaining_seconds, come directly from the server; no reminder is scheduled and no subscription is changed. Authentication uses --key, TICKDB_API_KEY, or local config, in that order.

This endpoint supplements the original documentation archive based on the user-provided screenshot and live verification; it is not present in that archive's OpenAPI snapshot.

API Key

You need a TickDB API key. Get one (free) at tickdb.ai.

Three ways to provide it (checked in this order):

1. --key flag: tickdb ticker BTCUSDT --key YOUR_KEY
2. Environment variable: export TICKDB_API_KEY=YOUR_KEY
3. Local config: tickdb config set-key YOUR_KEY

Keys are stored at ~/.config/tickdb/config.json.

Development

npm ci
npm test
npm run build
npm pack --dry-run

Tests cover all 43 in-scope GET request contracts, removed-parameter compatibility, pagination, output fields, errors, and real local gzip/Brotli transport. They also verify that full-market snapshot commands are unavailable. Contract tests use mock responses; they do not prove production data availability or require a production API key.

License

MIT