API: Watchlists

Creating and using stored lists of securities

J
Written by Jeremy Mulder
Updated over a week ago

Watchlists are containers for stored lists of securities. To get started using Watchlists, take the following steps:

First, a watchlist must be generated using the mutation.createWatchlist. Once a watchlist is generated, this container has the following properties:

Watchlist{
    id
    name
    alias
}

To add a list of securities into watchlists, use  mutation.addWatchlistSecurities:

mutation{
  addWatchlistSecurities(
    watchlistId: "my_wishlist"
    securities:{
      equities:[{
        ticker: "TSLA"
        mic: "XNAS"
      }]
    }
  ){
    name
    equities{
      id {
        ticker
        mic
      }
      addedOn
    }
  }
}

Once a watchlist is populated with securities, securities can be viewed in a watchlist along with the date they were added using the query.watchlist node. Here is an example watchlist with securities returned by the API in the following structure:

{
  "data": {
    "watchlist": {
      "alias": "my_wishlist",
      "equities": [
        {
          "id": {
            "ticker": "TSLA"
          },
          "addedOn": "2019-02-20"
        },
        {
          "id": {
            "ticker": "GOOG"
          },
          "addedOn": "2019-02-07"
        }
      ]
    }
  }
}

Watchlists as Universes

One way that watchlists are useful is that they can act as a universe - where certain operations can be limited to the names that are provided in the watchlist. 

For example, with security search a watchlist can be passed in as a universe filter. This will limit searching for securities based on certain characteristics only to the names inside the watchlist.

Using Watchlists in Optimization

Once a watchlist is saved, the stored securities in that watchlist can be used in conjunction with the Optimization API. 

The Optimization API takes in a securities input. This input can be supplied with a watchlist ID that the optimizer can either go long  or short with. In the example below, the watchlist is being passed in with the query variable $securities

Optimization Query With Securities Input

query (
  $positionSet: PositionSetInput,
  $constraints: OptimizationConstraints!,
  $securities: OptimizationSecuritiesInput
) {
  model(id: "AXWW4-MH") {
    optimization(
      objective: {minimizeTotalRisk: true},
      positionSet: $positionSet,
      constraints: $constraints,
      securities: $securities,
      on: "2017-06-30"
    ) {
      positions{
        dates{
          date
          equities{
            id{
              ticker
            }
            economicExposure
          }
        }
      }
    }
  }
}


Query Variables With Watchlists

{
  "securities": {
    "long": {
      "id": "my_wishlist",
      "type": "WATCHLIST"
    },
    "short": {
      "id": "hedges_list",
      "type": "WATCHLIST"
    }
  },
  "constraints": {
    "longMarketValue": 1000000,
    "shortMarketValue": 1000
  },
  "positionSet": {
    "type": "PORTFOLIO",
    "id": "portfolio_alias"
  }
}
Did this answer your question?