NAV Navbar
shell python

Introduction

Welcome to the Augmento developer documentation. These documents outline all the API functionality of the Augmento REST API and real-time Websocket API.

Augmento quantifies cryptocurrency-related activity associated with different topics and sentiments from data sources such as Twitter, Reddit, and Bitcointalk. This API provides these data historically and in real-time.

Change Log

Past

Date Change
22/05/2019 v0.1 - Initial public release
12/07/2020 v0.2 - Updated Api-Key header info
15/04/2024 v0.3 - Updated API URLs

REST API General

Overview

The REST API provides endpoints for collecting historical and up-to-the-minute data, as well as for getting information about the Augmento data.

The REST API URL is https://api.augmento.ai/v0.1/

Requests

All requests and responses are application/json content type and gzip compressed, and follow typical HTTP response status codes for success and failure. Requests for alternative response types will be ignored.

Errors

Unless otherwise stated, errors to bad requests will respond with HTTP 4xx or status codes. The body will also contain a message parameter indicating the cause. Your language’s http library should be configured to provide message bodies for non-2xx requests so that you can read the message field from the body.

404 error response

{
    "error": {
        "message": "not a valid endpoint",
        "name": "Not Found"
    }
}
Code Name Description
400 Bad Request Invalid request format
401 Unauthorized Invalid API key
404 Not Found Invalid endpoint
429 Too Many Requests Too many requests from this IP
500 Internal Server Error Problem with server
503 Service Unavailable API is temporarily offline

Success

A successful response is indicated by HTTP status code 200 and may contain an optional body. If the response has a body it will be documented under each of the resources below.

Pagination

The Augmento API uses offset pagination for serving time series data. Time steps are indexed from 0 to N-1 between the start_datetime and end_datetime. The start_ptr defines the index of the first time step of the response, and the count_ptr defines the number of time steps for the response following - and including - the first time step.

Parameters

Parameter Description
start_datetime Start time in ISO 8601
end_datetime End time in ISO 8601
start_ptr Index of first time step
count_ptr Number of time steps (1 - 1000)

Types

Timestamps

"2019-05-21T23:00:00Z"

All timestamps from API are returned in ISO 8601.

1558479600

All UTC timestamps are returned as integers, giving the number of seconds since 00:00:00 on the 1st of January 1970.

Rate Limits

Requests to the REST API are rate limited to 300 requests per 5 minutes. This counter refills continuously. If you are limited, you will receive a 429 response. Repeated violations of the rate limit will result in longer term bans.

On each request to the API, these headers are returned:

Header Description
X-RateLimit-Limit Max number of requests per 5 minutes
X-RateLimit-Remaining Number of requests remaining
X-RateLimit-Reset UTC time when another request becomes available
Retry-After Number of seconds before another request becomes available

Authentication

curl "https://api.augmento.ai/v0.1/events/aggregated?source=twitter&coin=bitcoin&bin_size=1H&count_ptr=10&start_ptr=0&start_datetime=2019-05-01T00:00:00Z&end_datetime=2019-05-06T00:00:00Z" --header "Api-Key: my-secret-api-key"  --compressed

import requests

url = "https://api.augmento.ai/v0.1/events/aggregated"

headers = {"Api-Key" : "my-secret-api-key"}

params = {
  "source" : "twitter",
  "coin" : "bitcoin",
  "bin_size" : "1H",
  "count_ptr" : 10,
  "start_ptr" : 0,
  "start_datetime" : "2019-05-01T00:00:00Z",
  "end_datetime" : "2019-05-06T00:00:00Z",
}

r = requests.request("GET", url, params=params, headers=headers)

print(r.content)

Response (valid key)

[
  {
    "counts": [0, 2, 5 ... 0, 5, 18], 
    "datetime": "2019-05-01T00:00:00Z", 
    "t_epoch": 1556668800
  }, 
  ... 
  {
    "counts": [0, 1, 2 ... 0, 2, 11], 
    "datetime": "2019-05-01T09:00:00Z", 
    "t_epoch": 1556701200
  }
]

Response (invalid key)

{
  "error": {
    "message": "API key in headers is invalid: {Api-Key : 'OGLo30YpahMcNnmJSR5Pd'}", 
    "name": "Unauthorized"
  }
}

Response (no key)

[]

All REST API endpoints are publically available, but some responses are limited without authentication. For example, timeseries data are provided up-to-the-minute with authentication, but only up until 30 days before the current date without authentication.

To authenticate, insert the secret API key into the header of the request:

Header Description
Api-Key my-secret-api-key

REST API Endpoints

Datetime

curl "https://api.augmento.ai/v0.1/datetime" --compressed

import requests

r = requests.request("GET", "https://api.augmento.ai/v0.1/datetime")

print(r.content)

Response

{
  "datetime": "2019-05-22T13:11:59Z", 
  "t_epoch": 1558530719
}

Request the current date and time.

HTTP Request

GET /datetime

Query Parameters

None

Sources

curl "https://api.augmento.ai/v0.1/sources" --compressed

import requests

r = requests.request("GET", "https://api.augmento.ai/v0.1/sources")

print(r.content)

Response

[
  "bitcointalk", 
  "reddit", 
  "twitter"
]

Request a list of all the available data sources.

HTTP Request

GET /sources

Query Parameters

None

Coins

curl "https://api.augmento.ai/v0.1/coins" --compressed

import requests

r = requests.request("GET", "https://api.augmento.ai/v0.1/coins")

print(r.content)

Response

[
  "0x", 
  "augur", 
  "bitcoin",
  ...
  "tron", 
  "vechain", 
  "verge", 
]

Request a list of all the available coins.

HTTP Request

GET /coins

URL Parameters

None

Bin sizes

curl "https://api.augmento.ai/v0.1/bin_sizes" --compressed

import requests

r = requests.request("GET", "https://api.augmento.ai/v0.1/bin_sizes")

print(r.content)

Response

{
  "1H": 3600, 
  "24H": 86400
}

Request a dictionary of all the available bin sizes. Bin size values are given in seconds, and represent the duration over which events have been aggreagated.

HTTP Request

GET /bin_sizes

URL Parameters

None

Topics

curl "https://api.augmento.ai/v0.1/topics" --compressed

import requests

r = requests.request("GET", "https://api.augmento.ai/v0.1/topics")

print(r.content)

Response

{
  "0": "Hacks", 
  "1": "Pessimistic/Doubtful", 
  "2": "Banks", 
  ...
  "90": "Airdrop", 
  "91": "Optimistic", 
  "92": "Negative"
}

Request a dictionary of all the topics and sentiments (values), and their corrisponding indexes for the event data (keys).

HTTP Request

GET /topics

URL Parameters

None

Aggregated Events

curl "https://api.augmento.ai/v0.1/events/aggregated?source=twitter&coin=bitcoin&bin_size=1H&count_ptr=10&start_ptr=0&start_datetime=2019-04-01T00:00:00Z&end_datetime=2019-04-06T00:00:00Z" --compressed

import requests

url = "https://api.augmento.ai/v0.1/events/aggregated"

params = {
  "source" : "twitter",
  "coin" : "bitcoin",
  "bin_size" : "1H",
  "count_ptr" : 10,
  "start_ptr" : 0,
  "start_datetime" : "2019-04-01T00:00:00Z",
  "end_datetime" : "2019-04-06T00:00:00Z",
}

r = requests.request("GET", url, params=params)

print(r.content)

Response

[
  {
    "counts": [0, 2, 1 ... 0, 2, 39], 
    "datetime": "2019-04-01T00:00:00Z", 
    "t_epoch": 1554076800
  }, 

  ...

  {
    "counts": [0, 0, 0 ... 0, 1, 8], 
    "datetime": "2019-04-01T09:00:00Z", 
    "t_epoch": 1554109200
  }
]

Request a list of aggregated event data for timesteps between start_datetime and end_datetime.

Note that data is available without authentication up until 30 days from now. For up-to-date data, please get in touch to request an API key.

HTTP Request

GET /events/aggregated

URL Parameters

Parameter Description
source Source of the data
coin Relevent coin
bin_size Length of bin
start_datetime Start time in ISO 8601
end_datetime End time in ISO 8601
start_ptr Index of first time step
count_ptr Number of time steps (1 - 1000)

Returns

Key Description
counts Event counts for each topic or sentiment binned by time, indexed by the keys returned in /topics
datetime ISO 8601 timestamp for the start of the bin
t_epoch UTC timestamp for the start of the bin

Websocket (depreciated)

Overview

"""
Note requirements:
  - Python 3.7 or later
  - websockets==6.0
"""

import asyncio
import websockets

url = "wss://ws.augmento.ai/v1/channels"

headers = {
  "channels": "bitcointalk,reddit,twitter",
  "Api-Key" : "my-api-key"
}

async def connect():
  async with websockets.connect(url, extra_headers=headers) as websocket:
    while True:
      results = await websocket.recv()
      print(results)

asyncio.get_event_loop().run_until_complete(connect())

Message

{
  "reddit": {
    "ripple": {
      "notopic": 1
    },
    "bitcoin": {
      "Fundamentals": 2,
      "Investing/Trading": 2,
      "Negative": 1,
      "Technology": 1
    },
    "ethereum": {
      "Bug": 1,
      "Fundamentals": 1,
      "Technology": 1,
      "Warning": 1
    }
  },
  "last_cursor": 1546018274,
  "timestamp": 1546018334.497455,
  "datetime": "2018-12-28 17:32:14"
}

The Augmento Websocket API provides an easy mechanism to periodically get the number of posts of crypto coins associated with differents topics and sentiments, by differents data sources such as Twitter, Reddit and Bitcointalk.

Default update frequency of 1 minute.

The Websocket API URL is wss://ws.augmento.ai/v1/channels

Authentication

In order to use the Websocket API, you should add a valid Api-Key in headers:

Header Description
Api-Key "my-secret-api-key"

Optional Headers

If you want to use selective channels, you just need to a add comma separated channels values in headers, if no channels header is provided, you are going to receive the information from all subscribed channels (default).

Header Description
channels One or more of the sources given by /sources
shell python