tdx-api: a REST API and web UI in front of a TDX client

A wrapper around the injoyai/tdx protocol client

The project description gives the whole idea in one line: a Go library for TDX stock data retrieval based on the TDX protocol, plus a web visualisation interface and a RESTful API.

The protocol work is not written here. The README credits the original author of injoyai/tdx, and the go.mod file confirms the relationship, since the module path is github.com/injoyai/tdx. The dependency list pulls in injoyai/base, injoyai/conv, injoyai/ios and injoyai/logs alongside xorm for storage, a cron library for scheduled work, a MySQL driver, a SQLite driver and golang.org/x/text for text handling. So this repository is a service layer and an interface on top of an existing client library, and the go.mod still declares go 1.20 as its language version.

That split explains the file layout. client.go, client_bj_code.go, codes.go, dial.go, hosts.go, manage.go, pool.go and workday.go sit at the repository root, protocol/ holds the protocol implementation, web/ holds the HTTP server, extend/ holds extra functionality, and example/ contains one directory per client method, from Connect and FastHosts through GetQuote, GetKlineDayAll, GetMinute, GetTrade, GetIndex, GetBjCodes and GetCodeAll.

The audience is a developer who wants machine readable market data for a script, a notebook or a dashboard, rather than a trader, and the README states that plainly in its disclaimer.

Thirty-two endpoints, from quote to scheduled pull tasks

The API surface is the substance of the project, and it is organised in three groups.

The core endpoints cover the everyday needs: /api/quote for the five level order book, /api/kline for K-line data, /api/minute for the intraday curve, /api/trade for tick by tick prints, /api/search for fuzzy lookup by code or name, and /api/stock-info for combined information. The extended group adds /api/codes and /api/stock-codes for the code lists, /api/batch-quote for many symbols at once, /api/kline-history and /api/kline-all for history, /api/kline-all/tdx and /api/kline-all/ths for the same full series from two different sources with the latter described as including forward adjustment, /api/index and /api/index/all for indices, /api/market-stats and /api/market-count for market wide figures, /api/etf-codes and /api/etf for funds, /api/trade-history and /api/trade-history/full for historical prints, /api/minute-trade-all for every intraday trade, and /api/workday and /api/workday/range for trading calendar queries.

The third group is the one that separates a service from a proxy. /api/tasks/pull-kline and /api/tasks/pull-trade create background pull tasks, /api/tasks lists them, and /api/income returns income data, while /api/server-status and /api/health expose the service state. The web/ directory mirrors that structure with server.go, server_api_extended.go and tasks.go.

The underlying Go client methods are named the same way, with GetQuote, GetKlineXXXAll, GetKlineDayAll, GetMinute, GetTrade and GetCodeAll listed in the supported data types table.

The source build fails in one specific way if you compile a single file

Two routes are documented, and the second one has a rule that is easy to miss.

The Docker route is the recommended one. Clone the repository, enter the directory, and start the compose file, then open the service on port 8080:

git clone https://github.com/oficcejo/tdx-api.git
cd tdx-api
docker-compose up -d

There is also a one-click script, docker-start.bat for Windows and docker-start.sh for Linux and Mac.

The source route needs Go 1.22 or newer, and the README is explicit that you must run the whole directory rather than a single file. The steps are to download the modules, enter the web directory and run it:

go mod download
cd web
go run .

The warning that accompanies it says you must use go run . to compile all Go files and that go run server.go must not be used. The reason is visible in the layout: the web package is split across server.go, server_api_extended.go and tasks.go, so compiling server.go alone leaves the extended endpoints and the task manager out of the binary.

Using the library directly from Go looks like this, and the import path is the upstream module:

import "github.com/injoyai/tdx"

c, _ := tdx.DialDefault(tdx.WithDebug(false))
quotes, _ := c.GetQuote("000001", "600519")
kline, _ := c.GetKlineDayAll("000001")

There is a Python usage example file in the repository as well, so a curl or requests based script is a supported path too.

The container runs as a non-root user and checks health twice, differently

The Dockerfile is a two stage build, and it is arranged around users inside China.

The builder stage uses golang:1.22-alpine, rewrites the Alpine repository URLs to mirrors.aliyun.com, sets GOPROXY to goproxy.cn and mirrors.aliyun.com/goproxy, disables CGO and targets linux and amd64. It copies the module files first, runs go mod download, then builds inside the web subdirectory with the output written to the parent directory.

The runtime stage starts from alpine:latest, adds ca-certificates, tzdata and wget, sets the time zone to Asia/Shanghai, creates a group and a user with id 1000, copies the binary and the static assets in, changes ownership and switches to that user with USER appuser. The service listens on 8080 and is started from the binary.

The compose file names the service stock-web with the container name tdx-stock-web, maps 8080 to 8080, sets restart to unless-stopped and the time zone environment variable, and puts it on a bridge network called stock-network.

One inconsistency is worth noting for anyone wiring monitoring. The compose healthcheck asks wget to spider http://localhost:8080/ every 30 seconds with a 3 second timeout and 3 retries, while the Dockerfile healthcheck probes http://localhost:8080/api/health. Two different endpoints, so a container that passes the image check tells you less about the API than it appears to.

Host selection is a fixed list of four public servers

The system connects to the fastest server automatically, and the README lists the candidates with their region and provider: 124.71.187.122 in Shanghai on Huawei cloud, 122.51.120.217 in Shanghai on Tencent cloud, 121.36.54.217 in Beijing on Huawei cloud and 124.71.85.110 in Guangzhou on Huawei cloud.

The example directory names support this reading of the design. FastHosts, DialHostsRange, CheckHosts and Connect are separate examples, and hosts.go and pool.go at the root suggest host management and a connection pool. The protocol/ directory holds the protocol implementation itself.

The constraint to keep in mind is that the list is fixed in the repository. There is no documented configuration file for adding your own server, and the README does not describe a fallback order or a health check for the hosts beyond the initial choice of the fastest one. If all four are unreachable or throttled, the documented behaviour is not there, which is a reasonable trade for a research tool and a poor one for anything running unattended.

The data types table maps the protocol calls to the market data: five level quotes with the real time bid and ask, volume, minute level K-lines across the 1, 5, 15, 30 and 60 minute periods, daily, weekly and monthly K-lines, intraday minute data, tick by tick trades and the full market code list. A separate document in the repository concerns forward adjustment handling, and the /api/kline-all/ths endpoint is described as coming from a second source with forward adjustment included.

Licensing, releases and the disclaimer that constrains use

Three facts about the project's standing should shape your expectations.

First, the licensing is stated two different ways. The README shows an MIT licence badge and a licence section saying MIT License, with a link to the LICENSE file. The repository licence metadata field, however, reads as unknown, which suggests GitHub could not classify the file automatically. The README text is the more specific statement, but if the licence matters to you, read the LICENSE file itself rather than trusting a badge or a metadata field.

Second, there are no GitHub releases for this repository, so there is no versioned artefact to pin. The last push was on 2026-06-27, and the build is a Docker image or a local go run in both cases, so the commit is your version.

Third, and most important, the README carries a three point disclaimer. The project is for study and research only, the data comes from TDX public servers and may be delayed, and nothing in it is investment advice. The delay point is not a formality: every latency-sensitive use of this data inherits it, and the licence in the repository does not change the fact that the upstream servers are public and unofficial.

Documentation coverage is good, if somewhat scattered. There is a full API document, a deployment guide, an integration guide, a Docker quick reference, an environment configuration guide, a project summary, an update log and a Python usage example, all in the repository root as separate files, some with Chinese names.

Where tdx-api is the wrong tool

There are clear cases where this project does not fit, and most of them come from the same source, the data.

The first is anything latency sensitive. The data comes from public servers and the project says it may be delayed, so a live trading decision, a stop loss or a market making loop built on it is working on information that is not guaranteed to be current.

The second is production deployment. There is no authentication described for the API, no rate limiting, and the host list is hardcoded with no documented failover. The compose file restarts the container unless stopped, which is convenient on a laptop and insufficient for a service anyone else depends on.

The third is a use case that needs a licensed data feed. This project reads a public protocol endpoint and the README is explicit that it is for learning and study. A commercial application redistributing this data needs a data agreement, and the disclaimer's wording is a clear signal of what the author intends.

The fourth is embedding the library under your own module path. The go.mod declares the module as github.com/injoyai/tdx, so this repository identifies itself with the upstream project. If you want the protocol client as a dependency in your own application, the import path to use is github.com/injoyai/tdx, and what this repository adds on top is the service, the endpoints and the interface.

The last is a maintenance judgement. With no releases, a last push on 2026-06-27 and a dependency list tied to a specific upstream library version, this is a project you deploy and then own.

Editorial conclusion

tdx-api fits a developer who wants JSON market data from TDX public servers for a script, a dashboard or a study, and it fits a Windows or Linux user who wants the service running through docker-compose without touching Go. It does not fit a production trading system, because the data comes from public servers that the project itself says may be delayed, and the host list is a fixed set of four addresses. Before adopting it, read the disclaimer in the README, check that the endpoint you need is in the API documentation file, and if you build from source, run the web directory with go run . exactly as the README insists rather than compiling a single file.

Frequently asked questions

Official sources

1. Issues
2. oficcejo/tdx-api on GitHub
3. README