API Access

TuringTrader.com provides an API to access your portfolio's asset allocation. You can use this API to automate portfolio maintenance and rebalancing.

API Access

The TuringTrader API provides a simple https endpoint, which returns the current asset allocation. The format of the URL is as follows:

https://www.turingtrader.com/api/v1/alloc?
    id=API_KEY&
    pf=PORTFOLIO_SLUG

This URL includes the following parameters:

  • API_KEY: The API key identifies you, similar to your account's login and password. You can find your API key on the member-info page.
  • PORTFOLIO_SLUG: This is the portfolio's name, as used in the URL of the portfolio page. If your portfolio's page is at www.turingtrader.com/classic-60-40, the slug is classic-40-40.

Here is an example of a valid URL: https://www.turingtrader.com/api/v1/alloc?id=123&pf=classic-60-40. The endpoint returns an object in JSON format, similar to this:

{
    portfolio: "classic-60-40",
    rebalanceDate: "October 13, 2020",
    columnFormat: ["Symbol", "Name", "Allocation", "Price"],
    assetAllocation: [
      ["SPY", "SPDR S&P 500 Trust ETF", "60.00%", "350.13"],
      ["TLT", "iShares 20 Plus Year Treasury Bond ETF", "40.00%", "161.75"],
    ],
}

The response includes the following fields:

  • portfolio: This is the portfolio slug you passed in as a parameter.
  • rebalanceDate: This is the date of the portfolio's last rebalancing. The date is specified in the exchange's time zone, and the asset allocation was calculated after the exchange closed on that day.
  • columnFormat: This field provides the format of the asset allocation rows. Each row includes the asset's ticker symbol, a descriptive name, the percentage of capital allocated to the asset, and the closing price.
  • assetAllocation: This is an array of arrays, one row per asset, with each row formatted according to columnFormat.

It is essential to understand that the API returns the portfolio allocation in its raw form before performing any additional data cleanup. Therefore, consumers of the asset allocation should watch out for the following:

  • The asset weights may add up to more than 100%. This can happen when prices move fast between the close on rebalancing day and the following open. Consumers should sum up the total asset weights, determine any excess exposure, and scale back the positions accordingly if required.
  • The asset weights may add up to less than 100%. This may happen when prices move fast before filling the rebalancing order or with portfolios that keep part of the capital in cash during bearish markets. Thus, consumers should assume that any unassigned capital is held in cash.

Automated Trading

There are many use cases for the API, but most of them relate to automating the rebalancing procedure. Most brokerages offer an API to query the account status and place orders, and a fully automated system can be created by scripting some glue logic to connect the two.

When considering a fully automated system, it is crucial to think about the following issues:

  • Perform the necessary cleanup steps before using the API data. See above for more details.
  • Check the rebalanceDate field and avoid rebalancing on days where this is not required. While the weights should be adjusted appropriately, rounding errors might still lead to additional churn.
  • Schedule all API operations late enough in the day. We recommend not relying on the API information any earlier than 5 hours after the markets closed. If possible, rebalancing should be scheduled closer to the market open.
  • The API might not return a separate row for assets with zero weight, leading to situations where the account may hold assets that are not mentioned in the allocation returned by the API. Your code will need to handle these situations.
  • Avoid rebalancing of tiny quantities. Brokerages often charge a minimum commission, and the value of the assets rebalanced should be much larger than this minimum commission.
  • Make sure to cancel any pending orders before submitting new orders. Otherwise, you might end up in situations where orders are emitted multiple times, leading to erroneous results.
  • Think long and hard about authentication. Do you store your account credentials somewhere? Can these be stolen or used in malicious ways? Can you avoid storing the credentials?

Broker APIs

Here is an incomplete list of brokerage APIs: