API Reference
Overview
Santiment API uses GraphQL. From the beginning it was decided to use GraphQL instead of REST for a number of reasons:
- You can request exactly the data you need and easily batch requests together. This is effectively handling the issues with underfetching and overfetching data. Why fetching all 20+ fields of a project when you only need its name?
- The request describes the format of the response. You no longer need to wonder what data the result contains and how to parse it.
- Easy out-of-the-box way to explore our API via our Live Explorer
Available Metrics
Full list of metrics can be found here.
Access the API
Some of the metrics are not available for free or are restricted - historical and realtime data is cut off. In order to explore them use slug
santiment
as it has full access without any restrictions.
There are different ways to fetch data from Santiment's API:
Live API Explorer
There is a live explorer, where you can run queries directly from the browser. The explorer is accessible here: https://api.santiment.net/graphiql
Here is an example of running a query and seeing the results directly in the browser:
GraphQL Request fetching transaction volume
A version of the GraphiQL that is useful to API users is https://api.santiment.net/graphiql_advanced
It allows adding HTTP headers, which can be used to add an API key, so the requests are authenticated.
To achieve this, add a header Authorization: Apikey <YOUR_OWN_API_KEY>
curl
The following GraphQL request will be passed as the body of the request:
1 2 3 4 5 6 7 8 9 10 11 12 13
{ getMetric(metric: "dev_activity") { timeseriesData( slug: "ethereum" from: "2020-02-10T07:00:00Z" to: "2020-03-10T07:00:00Z" interval: "1w" ) { datetime value } } }
Use the curl tool to get development activity of Ethereum. Copy and paste this curl request to your console:
1 2 3 4 5
curl \ -X POST \ -H "Content-Type: application/graphql" \ --data ' { getMetric(metric: "dev_activity"){ timeseriesData( slug: "ethereum" from: "2020-02-10T07:00:00Z" to: "2020-03-10T07:00:00Z" interval: "1w"){ datetime value } } }' https://api.santiment.net/graphql
A similar response is returned:
1
{"data":{"getMetric":{"timeseriesData":[{"datetime":"2020-02-13T00:00:00Z","value":1281.0},{"datetime":"2020-02-20T00:00:00Z","value":1115.0},{"datetime":"2020-02-27T00:00:00Z","value":952.0},{"datetime":"2020-03-05T00:00:00Z","value":605.0}]}}}
If you have the jq
tool installed it could help visuallize this response even
better:
1 2 3 4 5 6
curl \ -X POST \ -H "Content-Type: application/graphql" \ --data ' { getMetric(metric: "dev_activity"){ timeseriesData( slug: "ethereum" from: "2020-02-10T07:00:00Z" to: "2020-03-10T07:00:00Z" interval: "1w"){ datetime value } } }' https://api.santiment.net/graphql \ | jq .data.getMetric.timeseriesData
shows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
{
"datetime": "2020-02-13T00:00:00Z",
"value": 1281
},
{
"datetime": "2020-02-20T00:00:00Z",
"value": 1115
},
{
"datetime": "2020-02-27T00:00:00Z",
"value": 952
},
{
"datetime": "2020-03-05T00:00:00Z",
"value": 605
}
]
Santiment-provided Python library
There is a Python wrapper for the graphql API.
The library is called sanpy
and documentation and instructions how to install
can be found here
It can be installed via pip
1
pip install sanpy
The same ethereum development activity data with this library can be fetched like this:
1 2 3 4 5 6
san.get( "dev_activity/ethereum", from_date="2019-01-01T00:00:00Z", to_date="2019-01-07T00:00:00Z", interval="1d" )
The result is a pandas dataframe:
1 2 3 4 5 6 7
datetime activity 2019-01-01 00:00:00+00:00 44.0 2019-01-02 00:00:00+00:00 89.0 2019-01-03 00:00:00+00:00 140.0 2019-01-04 00:00:00+00:00 177.0 2019-01-05 00:00:00+00:00 46.0 2019-01-06 00:00:00+00:00 22.0
Programming language of your choice
In the san-sdk repository there are examples how to query the API with:
- R
- Ruby
- Elixir
- Javascript #1
- Plot Daily Active Addresses with Highchart
- Javascript #2
- Compute combined ETH balance of all projects
Authentication
Some of the APIs require a valid API key, belonging to an account with a paid subscription to access more data. The API key can be generated on your Account Settings page.
After that you need to pass the API key as an additional HTTP header
Authorization: Apikey <YOUR_OWN_API_KEY>
. An example how to do that using
curl:
1 2 3 4 5 6
curl \ -X POST \ -H "Content-Type: application/graphql" \ -H "Authorization: Apikey <YOUR_OWN_API_KEY>"\ --data '<YOUR_OWN_QUERY>' \ https://api.santiment.net/graphql
Errors
In case something is not correct with the request, the API will return an error. The API requests should always return status code 200, even if there was an error processing the request. An error response is going to include a description of the error that occured. For example here is what will happen if the query passed to the API is not valid:
1 2 3 4 5 6 7 8 9 10 11 12 13
$ curl \ -X POST \ -H "Content-Type: application/graphql" \ --data '{transactionVolume' \ https://api.santiment.net/graphql | jq .
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ curl \
-X POST \
-H "Content-Type: application/graphql" \
--data '{ transactionVolume(slug:"santiment", from:"2019-01-01T00:00:00Z") { datetime transactionVolume }}' \
https://api.santiment.net/graphql | jq .{
"errors": [
{
"locations":
{
"column": 3,
"line": 1
}
,
"message": "In argument \"to\": Expected type \"DateTime!\", found null."
}
]
} If the query does not return status code These headers show the limits applied to the currently authenticated users.
These values change only when the Sanapi subscription plan changes - whether when
it changes or when it expires. There are some terms used in this document like:200
, then something else is
happening. Here are some of the options:429
- you are being rate limited. Reduce the amount of requests you are
doing5xx
- an internal server error has occured. Let us know in the support
channel in our discord server