Skip to content

Upgrading to 1.7.0

1.7.0 rewrites how contracts work, bringing a new api.contracts query API and keeping contracts up to date automatically. Your existing code runs without changes, and you can move to the new API at your own pace.

What's new?

1. A smoother experience

  • No more managing contract updates yourself: previously you had to remember when contracts were refreshed and log in only after the update to get the latest ones — a particular hassle for futures night-session traders. From 1.7.0, contracts stay up to date automatically, so you no longer need to worry about update timing.
  • Faster login: login no longer downloads the full contract set; each security type is loaded automatically the first time you query it, so you can start right away.

2. New api.contracts query API

Query every product through a single api.contracts entry point, with query capabilities the legacy access doesn't have:

  • Unified lookup: use get() to look up any product (stocks, futures, indices…) without distinguishing security types.
  • Look up derivatives by underlying: find which futures or warrants exist for a given stock.
  • Filter by criteria: options and warrants can be filtered by strike price, expiry date, and more.
  • Richer contract details: the new info objects carry more complete fields — for example a stock's margin/short-selling balances, day-trade eligibility, and disposition/attention status — see Contract.

3. Stronger index support

  • Standardized index codes: indices now use their exchange codes (e.g. the TAIEX is IX0001), consistent with the exchange.
  • Real-time index quotes: subscribe to real-time quotes for indices (e.g. the TAIEX IX0001) — see Index Streaming.

How to migrate to 1.7?

1. What does not change

Most usage stays the same, including:

  • Legacy access such as api.Contracts.Stocks["2330"] and api.Contracts.Futures.TXF.TXFR1 still works.
  • Placing orders, subscribing to quotes, and querying historical data are unchanged.
  • Passing a queried contract to api.subscribe, api.kbars, order placement, etc. works the same as before.

2. Login arguments removed

login() no longer downloads contracts at login, so the fetch_contract, contracts_timeout, and contracts_cb arguments have been removed. Remove them from your login call.

api.login(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
    contracts_timeout=10000,
    contracts_cb=lambda st: print(f"{st} fetch done."),
)

api.login(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
)

3. Indices now use exchange codes

Indices now use their exchange codes (e.g. the TAIEX is IX0001); the pre-1.7.0 index codes (such as 001) no longer apply. If your code uses the old index codes, switch to the exchange codes.

api.Contracts.Indexs.TSE["001"]

api.Contracts.Indexs.TSE["IX0001"]

4. SecurityType.Future renamed to Futures

SecurityType.Future (singular) has been renamed to SecurityType.Futures (plural). Use the new name.

sj.SecurityType.Future

sj.SecurityType.Futures

5. Queried contract objects renamed

The objects returned when querying contracts have changed from Stock, Future, Option, Index to StockInfo, FuturesInfo, OptionInfo, IndexInfo (with a new WarrantInfo). Whether you query via api.Contracts (legacy) or api.contracts (new), you now get these info objects.

Some fields differ between the old and new objects; if your code references a field that only exists on the old objects (such as symbol), adjust it accordingly.

6. Listing contracts over HTTP is now a GET

This change only affects users who query contracts over HTTP (Python users are unaffected). In 1.5, listing contracts of a security type used POST /api/v1/data/contracts with a JSON body; 1.7.0 changes it to GET + query parameters:

curl -X POST http://localhost:8080/api/v1/data/contracts \
  -H "Content-Type: application/json" \
  -d '{"security_type":"STK","page":1,"page_size":3}'

curl "http://localhost:8080/api/v1/data/contracts?security_type=STK&page=1&page_size=3"

Looking up a single contract with GET /api/v1/data/contracts/{code} is unchanged. In addition, 1.7.0 adds several new query endpoints for futures, options, warrants, and more — see Contract for their usage.

Ready to go?

The legacy access still works, so you can move to api.contracts at your own pace. Start with Contract to learn the new query API.