Academy

Common Santiment API GraphQL Queries

Overview

In this article we explore some of the most frequently used queries in the SanAPI.

Retrieve data for one asset

This query obtains the daily active addresses for bitcoin for a period of 30 days.

1
2
3
4
5
6
7
8
9
10
11
12
{
  getMetric(metric: "daily_active_addresses"){
    timeseriesData(
      selector: {slug: "bitcoin"}
      from: "2024-01-01T00:00:00Z"
      to: "2024-01-31T23:59:59Z"
      interval: "1d"){
        datetime
        value
    }
  }
}

Retrieve data for one asset, apply some transformation - I

The development activity is very sensitive to day/night cycles, as well as public holidays or vacation days taken by the team. To smooth the data we can apply a moving average transformation to the data direclty in the API call.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  getMetric(metric: "dev_activity") {
    timeseriesData(
      slug: "ethereum"
      from: "utc_now-365d"
      to: "utc_now"
      interval: "7d"
      transform: {
       type: "moving_average"
       movingAverageBase: 4
      }) {
        datetime
        value
    }
  }
}

You can test this query in the GraphiQL Explorer.

Retrieve data for one asset, apply some transformation - II

The twitter_followers metric shows the total number of twitter followers of the handle of a project. If we apply the consecutive_difference we can directly see how the total number of followers changes week by week (because we use 7 day interval). The values show how many followers the project gained or lost for each time period. 

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  getMetric(metric: "twitter_followers") {
    timeseriesData(
      slug: "ethereum"
      from: "utc_now-365d"
      to: "utc_now"
      interval: "7d"
      transform: {type: "consecutive_differences"}) {
        datetime
        value
    }
  }
}

You can test this query in the GraphiQL Explorer.

Retrieve data for multiple assets with a single API call

This query obtains data for a list of assets in a single request. You can specify the assets by providing a list of their slugs using the slugs selector.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{ 
  getMetric(metric: "price_usd") {
    timeseriesDataPerSlug(
      from: "utc_now-1d"
      to: "utc_now"
      interval: "15m"
      selector: {slugs: ["ethereum","tezos","eos","color-platform","enecuum","slink"]})
      {
        datetime
        data {
          slug
          value
        }
      }
  }
}

You can test this query in the GraphiQL Explorer.

Note: If you want to retrieve the most recent data, you can use "utc_now" as the value for the to argument, instead of specifying a date.

Retrieving Prices at 1-Second Intervals

Only the price data with source cryptocompare is available at such small intervals.

If you need to fetch the price of a cryptocurrency that changes every second within a specific time frame, you can do so using our API.

Here is an example of how to retrieve the price of Bitcoin in USD at 1-second intervals for the past minute:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  getMetric(metric: "price_usd") {
    timeseriesData(
      selector: { slug: "bitcoin" source: "cryptocompare" }
      from: "utc_now-1m"
      to: "utc_now"
      interval: "1s"
      cachingParams: {baseTtl: 1, maxTtlOffset: 1}
    ) {
      datetime
      value
    }
  }
}

You can test this query in the GraphiQL Explorer.

Get some information about each project

Get some data for each project

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  allProjects {
    slug
    name
    ticker
    description
    logoUrl
    websiteLink
    twitterLink
    discordLink
    slackLink
    telegramLink
    facebookLink
    marketSegments
    githubLinks
    infrastructure
  }
}

You can test this query in the GraphiQL Explorer

Aggregate Data for Multiple Assets

If you need to retrieve the most recent MVRV data for multiple assets, such as Ethereum, Bitcoin, and Aave, you can accomplish this with a single query. The following is a simple solution:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  allProjects(
    selector: {
      baseProjects: {
        slugs: ["ethereum", "bitcoin", "aave"]
      }
    }) {
      slug
      aggregatedTimeseriesData(
        metric: "mvrv_usd_intraday_365d"
        from: "utc_now-1d"
        to: "utc_now"
        aggregation: LAST)
  }
}

You can test this query in the GraphiQL Explorer.

Get an aggregated value for each asset

The example below returns 3 values for each asset:

  • The latest known price in the last 24 hours, null if no new price is known;
  • The highest price of the past 7 days;
  • The total development activity for the past 30 days.
1
2
3
4
5
6
7
8
9
10
{
  allProjects(page: 1 pageSize: 100) {
    slug
    name
    ticker
    latestPrice: aggregatedTimeseriesData(metric: "price_usd" aggregation: LAST from: "utc_now-1d" to: "utc_now")
    highestWeeklyPrice: aggregatedTimeseriesData(metric: "price_usd" aggregation: MAX from: "utc_now-7d" to: "utc_now")
    devActivity30d: aggregatedTimeseriesData(metric: "dev_activity-1d" aggregation: SUM from: "utc_now-30d" to: "utc_now")
  }
}

Run the example

Filter and order assets and get data for them

The API allows for very complex queries that filter, order and paginate projects. The example below:

  • Runs on the watchlist stablecoins (one can use their own watchlists) with the addition of santiment, bitcoin and ethereum;
  • Keeps only those projects that have at least 1000 daily active addresses on average for the last 7 days;
  • Orders the result in descending order using the current daily active addresses;
  • Returns the first 10 projects according to these filter and orderding rules. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  allProjects(
    selector: {
      baseProjects: [{ watchlistSlug: "stablecoins" }, { slugs: ["santiment", "bitcoin", "ethereum"]}]
      filters: [
        {
          metric: "daily_active_addresses"
          from: "utc_now-7d"
          to: "utc_now"
          aggregation: AVG
          operator: GREATER_THAN
          threshold: 1000
        }
      ]
      orderBy: {
        metric: "daily_active_addresses"
        from: "utc_now-3d"
        to: "utc_now"
        aggregation: LAST
        direction: DESC
      }
      pagination: { page: 1, pageSize: 10 }
    }
  ) {
    slug
    avgDaa7d: aggregatedTimeseriesData(
      metric: "daily_active_addresses"
      from: "utc_now-7d"
      to: "utc_now"
      aggregation: AVG
    )
  }
}

Run the example

Retrieve all available projects for a specific metric

1
2
3
4
5
6
7
8
9
{
  getMetric(metric: "daily_active_addresses") {
    metadata {
      availableProjects{
          slug
      }
    }
  }
}

You can test this query in the GraphiQL Explorer.

Retrieve all available metrics for a specific project

1
2
3
4
5
6
7
8
9
10
{
  projectBySlug(slug: "bitcoin"){
    # All metrics
    availableMetrics
    # Only the timeseries metrics -- those that are fetched by getMetric's timeseriesData field
    availableTimeseriesMetrics
    # The available metrics paired with the link to their documentation
    availableMetricsExtended { metric docs { link } }
  }
}

You can test this query in the GraphiQL Explorer

Retrieve the access restrictions for each metric for a given subscription plan

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  getAccessRestrictions(filter: METRIC product: SANAPI plan: BUSINESS_PRO) {
    # Name of the metric
    name
    # Is the metric accessible at all, some metrics are not accessible in FREE plan
    isAccessible
    # If some time range restrictions are applied
    isRestricted
    # If the metric is scheduled for deprecation
    isDeprecated
    # What is the earliest date you can access. null if no restriction is applied
    restrictedFrom
    # What is the latest date you can access. null if no restriction is applied
    restrictedTo
    docs {
      link
    }
  }
}

You can test this query in the GraphiQL Explorer

Retrieve Current Prices for All Assets

1
2
3
4
5
6
7
8
9
10
{
  allProjects {
    slug
    price: aggregatedTimeseriesData(
      metric: "price_usd"
      from: "utc_now-1d"
      to: "utc_now"
      aggregation: LAST)
  }
}

You can test this query in the GraphiQL Explorer.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  getTrendingWords(
    from: "utc_now-3h"
    to: "utc_now"
    size: 20
    interval: "1h") {
      datetime
      topWords {
        word
        score
      }
  }
}

You can test this query in the GraphiQL Explorer.

Read next: Rate Limits

Updated 2 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