TuringTrader API Access

TuringTrader.com provides an API to access your portfolio's asset allocation. With this API, you can create your own applications in a programming language of your choice, or as macro-enabled spreadsheets, that pull portfolio allocations directly from our website. You can use this to track your investments, or to automate parts (or even all) of the rebalancing process.

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/portfolios/classic-60-40, the slug is classic-40-40. However, there is an additional complication. Occasionally, we release updated versions of our portfolios. In these cases, the slug contains a version number to distinguish between the strategy versions. If you are using version 3 of our All Stars Total Return portfolio, your slug is all-stars-tr-v3. We did this to make sure that you are not blindsided by portfolio updates on our end.

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 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.

Excel-based Rebalancing Tool

There are many use cases for the API, but most relate to automating at least part of the rebalancing procedure. To aid the development of custom rebalancing solutions, we provide sample code in the form of an Excel worksheet with VBA macros. This worksheet demonstrates accessing the API and interpreting the results.

Before using the tool for the first time, you need to perform the following setup steps:

• Enter your API key in field I5.
• Enter the portfolio slug in field E5.
• Optional: give your account a user-friendly name in field E4.

You are now ready to rebalance your account for the first time. This first rebalancing is slightly different because your account might not be all in cash but hold some positions. To reflect this, you need to manually enter the names of your assets in column A and the number of shares in column I.

The following steps are identical, whether you rebalance the account for the very first time or any subsequent rebalancing:

• Enter the current total account value in field E6. This value is the sum of the net liquidation value of all current positions, plus any excess cash held in the account. Please note that you need to manually update this value, even if you have saved the worksheet with the current holdings before.
• Click the Get Target Allocation button to retrieve the most recent asset allocation from TuringTrader.com.

Once the API request has finished, you have all the information required to rebalance your account:

• The last rebalancing date for this portfolio is in field A9.
• The target holdings for your account are in columns A to G.
• The orders required to rebalance the account are in columns J to L.

You can now prepare these orders and submit them to your broker. We recommend thinking about orders that affect only a small dollar amount, e.g., less than $500. Skipping these orders will have minimal effect on your account's performance but may significantly reduce friction due to fees, commissions, and slippage. Read more about this topic in our article about portfolio rebalancing.

Once you submitted your orders, you should click the button labeled Copy Target to Current Allocation. This will do the following:

• Set the field H9 to today's date.
• Copy the number of target shares from column G to column I.
• Clear the orders in columns J and L.
• Remove any rows with zero shares.

Don't forget to save the updated worksheet. Then, your next rebalancing will be much quicker, as you won't have to enter the current holdings.

Automated Trading

While the Excel-based rebalancing tool already saves a lot of time, some investors want to go further than this and fully automate their trading. 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 6 hours after the markets closed. If possible, rebalancing should be scheduled closer to the market opening.
• 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. Where and how do you store your account credentials? Can these be stolen or used in malicious ways? If at all possible, you should avoid storing your account credentials.