Go to Sanapi

Accessing the API

Overview
Access the API
Authentication
- GraphiQL API Explorer
- curl
Errors

Overview

Santiment API utilizes GraphQL. The reasons for choosing GraphQL over REST include:

It allows for precise data requests and easy batching of requests. This effectively addresses the problems of underfetching and overfetching data. For instance, why fetch all 20+ fields of a project when only its name is required?
The request outlines the format of the response. This eliminates the need to guess what data the result contains and how to parse it.
It provides an easy, ready-to-use method to explore our API via our Live Explorer.

Access the API

Please note that some metrics may not be freely available or may have restrictions, such as limited historical and real-time data. To explore these metrics without restrictions, use the slug santiment.

There are several methods to retrieve data from Santiment's API:

GraphiQL API Explorer

The GraphiQL (graphical interactive in-browser GraphQL IDE) allows you to run queries directly from your browser. You can access the explorer at the following link: https://api.santiment.net/graphiql.

Here's an example of how to run a query and view the results directly in your browser:

GraphQL Request fetching transaction volume

Python library

Santiment offers a Python wrapper for the GraphQL API, known as sanpy. You can find the documentation and installation instructions for this library here.

You can install sanpy using pip with the following command:

1
pip install sanpy

To fetch Ethereum development activity data using this library, use the following code:

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 will be a pandas dataframe, as shown below:

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, you can find examples of how to query the API using various programming languages. Here are some examples:

curl

The following GraphQL request will be executed with curl:

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
    }
  }
}

Copy and paste the following curl request into 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

The response should look similar to this:

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, you can use it to visualize the response more effectively:

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

The output should look like this:

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
  }
]

Authentication

Certain APIs necessitate a valid API key, which must be linked to an account with a paid subscription to access additional data. You can generate your API key on your Account Settings page.

After generating your API key, you need to include it as an additional HTTP header in the format Authorization: Apikey <YOUR_OWN_API_KEY>.

Authentication with GraphiQL Explorer

Santiment also offers an advanced version of GraphiQL that is particularly useful![] for API users: https://api.santiment.net/graphiql_advanced. This version allows users to add HTTP headers, which can be used to include an API key and authenticate your requests. To do this, simply add the following header: Authorization: Apikey YOUR_OWN_API_KEY.

Authentication with curl

Include the Authorization: Apikey <YOUR_OWN_API_KEY> header using the -H option:

1
2
3
4
5
6
curl \
  -X POST \
  -H "Content-Type: application/graphql" \
  -H "Authorization: Apikey <YOUR_OWN_API_KEY>"\
  --data '{ curentUser { id} }' \
  https://api.santiment.net/graphql

Errors

GraphQL errors are returned with HTTP status code 200.

To check for errors, you need to check for the presence of the errors key in the JSON response.

If the query does not return a status code of 200, it indicates a different issue. Here are some possibilities:

429 - You're being rate-limited. Reduce the number of requests you're making. Check the Rate limits page for more information.
5xx - An internal server error has occurred. Please let us know in the support channel on our Discord server.

Error example - syntax error

For instance, if an invalid query is passed to the API, the following will occur:

1
2
3
4
5
$ 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
{
  "errors": [
    {
      "message": "syntax error before: ",
      "locations": [
        {
          "line": 1,
          "column": 2
        }
      ]
    }
  ]
}

Error example - missing parameter

If your query is missing an argument, the error response will describe this:

1
2
3
4
5
$  curl \
  -X POST \
  -H "Content-Type: application/graphql" \
  --data '{ getMetric(metric: "price_usd"){ timeseriesData(slug: "bitcoin"){ datetime value } } }' \
  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
20
21
22
{
  "errors": [
    {
      "message": "In argument \"to\": Expected type \"DateTime!\", found null.",
      "locations": [
        {
          "line": 1,
          "column": 34
        }
      ]
    },
    {
      "message": "In argument \"from\": Expected type \"DateTime!\", found null.",
      "locations": [
        {
          "line": 1,
          "column": 34
        }
      ]
    }
  ]
}

Error example - historical and realtime data restriction

If the from and/or to parameters are outside of the allowed interval for the subscription plan and Historical and Realtime data restrictions are applied, the error will look like this:

1
2
3
4
5
$ curl \
  -X POST \
  -H "Content-Type: application/graphql" \
  --data '{ getMetric(metric: "mvrv_usd_1d"){ timeseriesData(slug: "bitcoin" from: "2015-01-01T00:00:00Z" to: "2016-01-01T00:00:00Z"){ datetime value } } }' \
  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
20
21
22
{
  "data": {
    "getMetric": {
      "timeseriesData": null
    }
  },
  "errors": [
    {
      "message": "Both `from` and `to` parameters are outside the allowed interval you can query mvrv_usd_1d with your current subscription SANAPI FREE. Upgrade to a higher tier in order to access more data.\n\nAllowed time restrictions:\n  - `from` - 2023-07-05 10:02:53.682000Z\n  - `to` - 2024-06-04 10:02:53.682000Z\n",
      "path": [
        "getMetric",
        "timeseriesData"
      ],
      "locations": [
        {
          "line": 1,
          "column": 37
        }
      ]
    }
  ]
}

Read next: Fetching Metrics

Updated 4 months ago

Talk to us in Discord

Still have some questions left? Join our Discord and get help from the Santiment team!

Go to Discord

Getting started

Guides

Resources