Santiment API

Santiment GraphQL API

Query the Santiment API — a GraphQL platform providing 750+ metrics for 2,000+ crypto assets across 12 blockchains. Fetch on-chain, financial, social, and development data for the cryptocurrency market.

Endpoint and Authentication

• GraphQL endpoint: https://api.santiment.net/graphql
• Interactive explorer: https://api.santiment.net/graphiql

Every request requires an API key in the Authorization header (Authorization: Apikey <KEY>). The user must provide their own key — never hardcode or assume one. If $SANTIMENT_API_KEY is set in the environment, use it directly. Otherwise, ask the user for their key (free tier available at https://app.santiment.net/account#api-keys).

All requests are HTTP POST with Content-Type: application/json. Use GraphQL variables to separate the query template from runtime values — this avoids quote-escaping errors. In curl, use a heredoc with a quoted delimiter (<< 'QUERY') so the shell doesn't interpret $variable as environment variables.

curl -s -X POST https://api.santiment.net/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey $SANTIMENT_API_KEY" \
  -d @- << 'QUERY'
{
  "query": "query($metric: String!, $slug: String, $from: DateTime!, $to: DateTime!, $interval: interval) { getMetric(metric: $metric) { timeseriesData(slug: $slug, from: $from, to: $to, interval: $interval) { datetime value } } }",
  "variables": {
    "metric": "price_usd",
    "slug": "bitcoin",
    "from": "utc_now-7d",
    "to": "utc_now",
    "interval": "1d"
  }
}
QUERY

Variable Types

Use these GraphQL types in query(...) variable declarations:

Core Query: getMetric

Nearly all data flows through getMetric. Pass a metric name string and then select one sub-field that determines the shape of the response data.

Sub-fields

Choose exactly one sub-field per getMetric call:

Parameters

These parameters are passed to the sub-field, not to getMetric itself:

Important: slug and selector are mutually exclusive. Use slug for simple single-asset queries. Use selector when querying multiple slugs at once ({ slugs: [...] }) or when a metric requires additional selector fields like holdersCount or owner.

Relative Time Expressions

The from and to fields accept relative expressions: utc_now-<N><unit> where unit is d (day), w (week), m (month), or y (year). Preferred over hardcoded dates.

• "utc_now" — current time
• "utc_now-7d" — 7 days ago
• "utc_now-1m" — 1 month ago
• "utc_now-1y" — 1 year ago

Transforms

Apply transforms directly in the query to post-process data server-side. Pass the transform parameter to timeseriesData:

Transforms reduce the number of returned data points by N-1 for moving averages. Request a slightly wider time range to compensate.

Dynamic Discovery

When you don't know the exact metric name for a user's request, follow this 3-step workflow. Always prefer dynamic discovery over hardcoded values.

Step 1 — Fetch the metric list

{
  getAvailableMetrics
}

Returns 1,000+ snake_case strings. The response is large — save to a file with -o and read it directly (e.g., open() in Python). Do not pipe the contents through stdin at any stage — neither from curl nor when processing the file afterward:

curl -s -X POST https://api.santiment.net/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <YOUR_API_KEY>" \
  -d '{"query": "{ getAvailableMetrics }"}' \
  -o /tmp/santiment-metrics.json

Filter by plan with getAvailableMetrics(product: SANAPI, plan: BUSINESS_PRO).

Step 2 — Search by keywords

Search the saved file for keywords matching user intent. Example: whale activity → search for holder, top, whale, supply, amount_in. See references/metrics-catalog.md for intent-to-keyword mappings.

Step 3 — Inspect metadata before querying

Once you have candidate metrics, fetch metadata to confirm compatibility:

{
  getMetric(metric: "amount_in_top_holders") {
    metadata {
      availableSlugs
      availableAggregations
      availableSelectors
      dataType
      defaultAggregation
      minInterval
    }
  }
}

This reveals required selectors (e.g., holdersCount), supported slugs, and minimum interval. Requesting a smaller interval than minInterval returns an error. See examples/query-patterns.md example 5 for a worked example.

Find a project's slug

Look up a specific project by slug to verify it exists and see its details:

{
  projectBySlug(slug: "bitcoin") {
    slug
    name
    ticker
    infrastructure
  }
}

Browse all projects paginated (useful when the user provides a token name or ticker instead of a slug):

{
  allProjects(page: 1, pageSize: 50) {
    slug
    name
    ticker
  }
}

Check data availability for a metric and slug

Before making a large timeseries query, verify that data exists for the desired metric-slug combination and check freshness:

{
  getMetric(metric: "daily_active_addresses") {
    availableSince(slug: "ethereum")
    lastDatetimeComputedAt(slug: "ethereum")
  }
}

Check access restrictions for your plan

Understand what historical range your API key can access for each metric. Call this to avoid wasted queries that would return restriction errors:

{
  getAccessRestrictions(product: SANAPI, plan: BUSINESS_PRO, filter: METRIC) {
    name
    isAccessible
    isRestricted
    restrictedFrom
    restrictedTo
    minInterval
  }
}

Error Handling

The API always returns HTTP 200, even for errors. Always parse the JSON and check for the errors array.

A typical error response:

{
  "data": { "getMetric": null },
  "errors": [
    {
      "message": "The metric 'nonexistent_metric' is not a valid metric.",
      "locations": [{ "line": 2, "column": 3 }]
    }
  ]
}

When data contains null and errors is present, the query failed. Common errors:

Empty data is not the same as zero data. When timeseriesData returns [] without errors, do NOT tell the user there is no activity. On-chain metrics are only computed for indexed chains. Check references/metrics-catalog.md Ghost Data section for the diagnostic flow.

The one exception to the HTTP 200 rule is rate limiting: HTTP 429 means the account's quota is exhausted. See references/rate-limits.md for details.

Quick Reference: Building a Query

Follow these steps to construct any Santiment API query:

1. Pick a metric — use directly if known, otherwise follow Discovery Workflow.
2. Pick a slug — resolve names/tickers via projectBySlug or allProjects.
3. Pick a time range — relative expressions preferred. Check availableSince first.
4. Pick an interval — "1d", "1h", "7d". Larger intervals reduce complexity.
5. Pick a sub-field — timeseriesData for series, aggregatedTimeseriesData for single value, timeseriesDataPerSlugJson for multi-asset.
6. Optionally add — transform, selector (instead of slug), or aggregation override.
7. If data is empty — check availableSince for epoch. If epoch, the metric isn't computed for this slug's chain. Report unavailability and suggest alternative metrics.

Execute via curl with the user's API key and parse the JSON response. Always check for the errors array before processing data.

Additional Resources

Consult these reference files for detailed information:

• Metrics catalog — references/metrics-catalog.md — keyword-to-metric mapping for translating user intent into search terms, plus 20 curated quick-reference metrics and naming conventions
• Rate limits — references/rate-limits.md — tier limits, complexity scoring, and optimization strategies to avoid quota exhaustion
• Query patterns — examples/query-patterns.md — 6 worked examples with both GraphQL and curl, including discovery workflow and ghost data diagnostics