Stocktwits Firehose

Methods

Method	Description
GET /stream	Connect to the data stream.
GET /stream/v2	Connect to the same stream with better sequence recovery.

Authentication

All requests to Firehose stream APIs must use HTTP Basic Authentication, constructed from the username and password combination used to log into this site.

GET /stream/v2

Establishes a persistent connection to the Firehose stream. Everything is the same as /stream with the addition of one field.

Stream Differences

Request Params	The last sequence id received can be specified, the stream will attempt to continue from that point unless too many messages have been sent since that sequence. https://firehose.stocktwits.com/stream?last_sequence_id=123456
Data Format Addition	The last sequence id is passed since messages can be streamed in an order different then their message ids due to different speeds of processing. "firehose_seq" : 123456

GET /stream

Establishes a persistent connection to the Firehose stream, through which the realtime data will be delivered.

Request Specifications

Request Method	HTTP GET
Connection Type	Keep-Alive This should be specified in the header of the request.
URL	Found on the stream's API Help page of your dashboard, using the following structure: https://firehose.stocktwits.com/stream
Params	The last message received can be specified, the stream will attempt to continue from that point (if the message was sent in the past 15 minutes). https://firehose.stocktwits.com/stream?last_message_id=5555558
Compression	Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following: Accept-Encoding: gzip
Read Timeout	Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds.

Responses

The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect.

Status	Text	Description
200	Success	The connection was successfully opened, and new activities will be sent through as they arrive.
401	Unauthorized	HTTP authentication failed due to invalid credentials. Verify that your login combination matches this sites.
406	Not Acceptable	Generally, this occurs where your client fails to properly include the headers to accept gzip encoding from the stream, but can occur in other circumstances as well. Will contain a JSON message similar to "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end."
429	Rate Limited	Your app has exceeded the limit on connection requests.
503	Service Unavailable	stocktwits server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on this site under status, email support@stocktwits.com.

Example curl Request

The following example request is accomplished using cURL on the command line.

curl --no-buffer -uusername "https://firehose.stocktwits.com/stream"

Data Format

verb

All messages are currently labeled in this way

"verb" : "post"

A unique ID for the activity.

"id" : "tag:firehose.stocktwits.com:note/21637714"

body

The activity's text.

"body" : "$AAPL is going down"

link

A link to the post.

"link" : "http://stocktwits.com/userName/message/10047145"

inReplyTo

If the current activity is a reply, this is an object containing information about the parent activity and will contain a unique IRI for the activity being replied to.

NULL
or
"inReplyTo" : {  
  "objectType" : "note",
  "id" : "tag:firehose.stocktwits.com:note/21637177"
}

sharedNote

If the current activity is a share, this is an object containing information about the parent message and will contain a unique IRI for the message being replied to.

NULL
or
"sharedNote" : {  
  "objectType" : "note",
  "id" : "tag:firehose.stocktwits.com:note/21637177"
}

actor

An object representing the StockTwits user who posted the activity.
Show Sub-field Details

Property	Description
id	A unique IRI for the StockTwits user. "id" : "person:stocktwits:183087"
objectType	"person" "objectType": "person"
preferredUsername	The user's user name. "preferredUsername" : "userName"
displayName	The user's name "displayName" : "User Name"
image	The url of the user's avatar. "image" : "http://avatars.stocktwits.com/production/183087/thumb-1350332393.png"
classification	Types of users. Can be "suggested" (suggested by stocktwits), "ir" (official company investor relations), "pro" (professionals that attach message disclosures), or "official" (verified accounts). "classification" : [ "suggested" ]
followersCount	The number of followers the user has. "followersCount" : 0
followingCount	The number of other users that this user follows. "followingCount" : 0
followingStocksCount	The number of stocks the user follows. "followingStocksCount" : 0
link	A link to user's page on stocktwits.com. "link" : "http://stocktwits.com/userName"
links	Links to the user's pages on other platforms (e.g. Twitter). "links" : [ { "href" : null, "rel" : "me" } ]
statusesCount	The number of posts the user has made. "statusesCount" : 200
summary	The user's bio. Will be null if no bio is present. "summary" : "A person who likes stocks"
tradingStrategy	An object containing info about the user's trading strategy. Options found at: http://stocktwits.com/settings/profile/strategy "tradingStrategy" : { "approach" : "Technical", "assetsFrequentlyTraded" : [ "Forex" ], "experience" : "Novice", "holdingPeriod" : "Day Trader"

"actor" : {
  "objectType" : "person",
  "displayName" : "name",
  "preferredUsername" : "userName",
  "followersCount" : 0,
  "followingCount" : 0,
  "followingStocksCount" : 0,
  "id" : "person:stocktwits:183087",
  "image" : "http://avatars.stocktwits.com/path-to-users-avatar.png",
  "link" : "http://stocktwits.com/userName",
  "links" :
  [{
    "href" : "http://userName.com/users/personal-site",
    "rel" : "me"
  }],
  "statusesCount" : 200,
  "summary" : null,
  "tradingStrategy" :
  {
    "approach" : "Technical",
    "assetsFrequentlyTraded" :
    [
      "Forex"
    ],
    "experience" : "Novice",
    "holdingPeriod" : "Day Trader"
  },
  "classification" : [
      "suggested"
  ]
}

object

A JSON object representing the note being posted.
Show Sub-field Details

Property	Description
id	A unique IRI for the StockTwits message. "id" : "note:stocktwits:10047145"
objectType	"note" "objectType" : "note"
summary	The text of the StockTwits activity. "summary" : "$BCOIN and macd is going down ..... http://stks.co/iDEB"
postedTime	The creation time of the StockTwits note. "postedTime" : "2012-10-17T19:13:50Z"
updatedTime	The updated time of the StockTwits note. "updatedTime" : "2012-10-17T19:13:50Z"
link	A link to the post. "link" : "http://stocktwits.com/userName/message/10047145"

"object" :
{
    "id" : "note:stocktwits:10047145",
    "link" : "http://stocktwits.com/myselfbtc/message/10047145",
    "objectType" : "note",
    "postedTime" : "2012-10-17T19:13:50Z",
    "summary" : "$BCOIN and macd is going down ..... http://stks.co/iDEB",
    "updatedTime" : "2012-10-17T19:13:50Z"
}

entities

The entities object from the StockTwits data format. It can contain charts, sentiment, stock symbols, and videos associated with the activity.
Show Sub-field Details

Property	Description
chart	An object containing information about a chart that user added to the activity. This may contain a link and image references to the chart. "chart" : { "thumb": "http://charts.stocktwits.com/production/small_31307994.png", "large": "http://charts.stocktwits.com/production/large_31307994.png", "original": "http://charts.stocktwits.com/production/original_31307994.png", "url": "http://stks.co/g1Ye8" }
sentiment	An object containing a the user-defined sentiment. Can be "Bearish", "Bullish", or null. "sentiment" : { "basic" : "Bearish" }
stocks	An object containing information about any stock tickers extracted from the message by stocktwits. This can include "displayName", "exchange", "industry", "sector", "stocktwits_id", and "symbol" fields. Trending is true/false if the stock is currently trending on stocktwits. "symbols" : [ { "displayName":"Deere & Company", "stocktwits_id":4940, "symbol":"DE", "exchange":"NYSE", "industry":"Farm & Construction Machinery", "sector":"Industrial Goods", "trending":false } ]
video	An object containing information about a video that the user added to the activity. This feature is currently disabled. NULL

"entities" :
{
  "chart" : {
    "thumb": "http://charts.stocktwits.com/production/small_31307994.png",
    "large": "http://charts.stocktwits.com/production/large_31307994.png",
    "original": "http://charts.stocktwits.com/production/original_31307994.png",
    "url": "http://stks.co/g1Ye8"
  },
  "sentiment" :
  {
    "basic" : "Bearish"
  },
  "stocks" : [
    {
      "displayName":"Deere & Company",
      "stocktwits_id":4940,
      "symbol":"DE",
      "exchange":"NYSE",
      "industry":"Farm & Construction Machinery",
      "sector":"Industrial Goods",
      "trending":false
    }
  ],
  "video" : null
}

Sample Payload

StockTwits Post Activity

{  
   "verb":"post",
   "id":"tag:firehose.stocktwits.com:note/21637714",
   "body":"Contains the body message",
   "actor":{  
      "id":"person:stocktwits:275917",
      "objectType":"person",
      "displayName":"name",
      "preferredUsername":"userName",
      "followersCount":10,
      "followingCount":5,
      "followingStocksCount":5,
      "statusesCount":300,
      "summary":"user bio or NULL if not present",
      "links":[  
         {  
            "href":"URL to personal website or NULL if not present",
            "rel":"me"
         }
      ],
      "link":"http://stocktwits.com/userName",
      "image":"http://avatars.stocktwits.com/path-to-users-avatar.png",
      "tradingStrategy":{  
         "assetsFrequentlyTraded":[  
            "Equities"
         ],
         "approach":"Momentum",
         "holdingPeriod":"Swing Trader",
         "experience":"Novice"
      },
      "classification":[  

      ]
   },
   "object":{  
      "id":"note:stocktwits:21637714",
      "objectType":"note",
      "postedTime":"2014-04-01T20:50:50Z",
      "updatedTime":"2014-04-01T20:50:50Z",
      "summary":"Contains the body message",
      "link":"http://stocktwits.com/userName/message/21637714"
   },
   "provider":{  
      "displayName":"StockTwits",
      "link":"http://stocktwits.com"
   },
   "link":"http://stocktwits.com/userName/message/21637714",
   "entities":{  
      "symbols":[  
        {
          "displayName":"Deere & Company",
          "stocktwits_id":4940,
          "symbol":"DE",
          "exchange":"NYSE",
          "industry":"Farm & Construction Machinery",
          "sector":"Industrial Goods",
          "trending":false
        }
      ],
      "sentiment": {"basic": "Bullish"},
      "chart":
        {
          "thumb": "http://charts.stocktwits.com/production/small_31307994.png",
          "large": "http://charts.stocktwits.com/production/large_31307994.png",
          "original": "http://charts.stocktwits.com/production/original_31307994.png",
          "url": "http://stks.co/g1Ye8"
        },
      "video":null
   },
   "inReplyTo":{  
      "objectType":"note",
      "id":"tag:firehose.stocktwits.com:note/21637177"
   }
}