Data Portal » API Data Feeds » Trade Ideas Program API » Documentation

Trade Ideas Program API

Table of contents

Table of contents

Documentation
Overview and quick start
Authentication and authorization
Example usage
How to query
Error handling
Changelog
Version 1

How to query

You can use the query below to get the latest content matching your API subscription:

curl -H 'Authorization: Bearer YOUR_API_KEY' https://ideasequities.timgroup.com/api/v1/stream/{stream_id}/{event_number}/{batch_size}

Where:

  • {stream_id} is the identifier for a given steam.
  • {event_number} is the last event number processed (-1 is the start).
  • {batch_size} is the maximum number of events to return, capped at 1000.

The server will return as many events as specified in the The server will return as many events as specified in the {batch_size} or as many as are available, whichever is smaller. When no events are returned the end of the stream has been reached.

When no new events are available the server will hold the connection open until new events are available, for up to five seconds. This means events will be pushed to the client as soon as they become available in the system. The header ‘X-Long-Poll’ can be used to configure how long the server should hold the connection open awaiting new events.

Given a stream with five events, numbered 0 to 4, the following would return immediately with event 4:

curl -H 'Authorization: Bearer YOUR_API_KEY' -H 'X-Long-Poll: 10' https://ideasequities.timgroup.com/api/v1/stream/{stream_id}/3/5

Given the same stream of five events, the below would return after 10 seconds or when the event with number 5 is published:

curl -H 'Authorization: Bearer YOUR_API_KEY' -H 'X-Long-Poll: 10' https://ideasequities.timgroup.com/api/v1/stream/{stream_id}/4/5

If the intent is to subscribe to the live stream, a new request should be made whenever the previous has completed. When there are no new events the same request is repeated. Otherwise the event number is updated to that of the last processed event.

To get the latest event number the following will give you the most recent ten events:

curl -H 'Authorization: Bearer YOUR_API_KEY' https://ideasequities.timgroup.com/api/v1/stream/{stream_id}/

Response

Ideas are represented as an ordered sequence of events (e.g. opened, updated, closed) with a correlation identifier. To construct the current state of an Idea all of its events must be processed in the provided order. If there is a problem with an event, the system will stop publishing new events to protect data integrity until Acuris has resolved the underlying issue.

The following is an example of an ‘IdeaOpened’ event:

{ 
  "event_number": 123, 
  "event_type": "IdeaOpened", 
  "data": { 
    "id": "2d1885ed419f4b758dc5f75183dea485", 
    "timestamp": "2018-06-04T14:34:43.393Z", 
    "published_at": "2018-06-04T14:34:43.393Z", 
    "origin": "User", 
    "comment": "hedge long positon in Eni", 
    "idea": { 
      "state": "open", 
      "open_timestamp": "2018-06-04T14:34:43.393Z", 
      "close_timestamp": null, 
      "author": { 
        "id": "57f8f7f0bd56490eba6a6af42d2da304", 
        "first_name": "Anthony",  
        "last_name": "Davis", 
        "location": { 
          "city": "London", 
          "country": "GBR", 
          "region": "United Kingdom" 
        }, 
        "company": { 
          "id": "23d3295287ea40f28567e3aefb5337f5", 
          "name": "Big Bank" 
        } 
      }, 
      "conviction": "High", 
      "size": "MEDIUM", 
      "web_link": null, 
      "time_horizon": "< 3 month", 
      "stop_loss": null, 
      "recommendations": [ 
        { 
          "public_id": "TIM-WEB-abc123",  
          "instrument": { 
            "public_id": "2fbbff04ddb2c97c576cd72a0a8bd5da", 
            "ric": "EQNR.OL", 
            "bloomberg_ticker": "EQNR NO", 
            "figi": "BBG000NSV6T3" 
          }, 
          "direction": "SHORT", 
          "target_price": { 
            "value": "191.65000000000000000", 
            "currency": "NOK" 
          }, 
          "current_investment": { 
            "value": 1000000, 
            "currency": "EUR" 
          } 
        } 
      ] 
    } 
  }
} 

The following is an example of an ‘IdeaUpdated’ event:

{ 
  "event_number": 124, 
  "event_type": "IdeaUpdated", 
  "data": { 
    "id": "cdce479cf8a045e5b7c6460d70785131", 
    "timestamp": "2018-06-04T14:33:07.685Z", 
    "published_at": "2018-06-04T14:33:07.685Z", 
    "origin": "User", 
    "comment": "increasing investment", 
    "idea": { 
      "state": "open", 
      "open_timestamp": "2018-05-28T15:11:13.992Z", 
      "close_timestamp": null, 
      "author": { 
        "id": "3f0c3d557ea342f3b19b2b867a283a61", 
        "first_name": "Daryl",  
        "last_name": "Hopkins", 
        "location": { 
          "city": "New York", 
          "country": "USA", 
          "region": "North America" 
        }, 
        "company": { 
          "id": "23d3295287ea40f28567e3aefb5337f5", 
          "name": "Big Bank" 
        } 
      }, 
      "conviction": "High", 
      "size": "MEDIUM", 
      "web_link": null, 
      "time_horizon": null, 
      "stop_loss": "0.05", 
      "recommendations": [ 
        { 
          "public_id": "TIM-WEB-def456", 
          "instrument": { 
            "public_id": "0d98b597aa732aea606bde680c3b57d8", 
            "ric": "RCL", 
            "bloomberg_ticker": "RCL US", 
            "figi": "BBG000BB5792" 
          }, 
          "direction": "SHORT", 
          "target_price": null, 
          "current_investment": { 
            "value": 4000000, 
            "currency": "USD" 
          } 
        } 
      ]
    } 
  } 
}

The following is an example of an ‘IdeaClosed’ event:

{ 
  "event_number": 125, 
  "event_type": "IdeaClosed", 
  "data": { 
    "id": "f9f5c34ab7204308ab87689f04a492dd", 
    "timestamp": "2018-06-04T14:35:11.225Z", 
    "published_at": "2018-06-04T14:35:11.225Z", 
    "origin": "User", 
    "comment": "stop loss", 
    "idea": { 
      "state": "closed", 
      "open_timestamp": "2018-05-21T18:57:00.623Z", 
      "close_timestamp": "2018-06-04T14:35:11.225Z", 
      "author": { 
        "id": "68a699431511499bb69535151a913bf5", 
        "first_name": "Clavis",  
        "last_name": "Tuan", 
        "location": { 
          "city": "New York", 
          "country": "USA", 
          "region": "North America" 
        }, 
        "company": { 
          "id": "23d3295287ea40f28567e3aefb5337f5", 
          "name": "Big Bank" 
        } 
      }, 
      "conviction": "Very high", 
      "size": "LARGE", 
      "web_link": null, 
      "time_horizon": null,
      "stop_loss": "0.1", 
      "recommendations": [ 
        { 
          "public_id": "TIM-WEB-ghi789", 
          "instrument": { 
            "public_id": "acc21473c4525b922286130ffbfe00b5", 
            "ric": "JCP", 
            "bloomberg_ticker": "JCP US", 
            "figi": "BBG000BMF5J0" 
          }, 
          "direction": "SHORT", 
          "target_price": null, 
          "current_investment": { 
            "value": 0, 
            "currency": "USD" 
          } 
        } 
      ] 
    } 
  } 
}