Skip to main content

How to Run a Hosted Subgraph with Satsuma

Updated on
Sep 30, 2023

4 min read


This add-on is no longer available for new installations. Only users who previously installed it can access and use it.


In the fast-paced yet often unpredictable world of Web3 engineering, teams consistently face considerable challenges when running hosted subgraphs, such as downtime, data lag, sluggish reindexes, slow queries, and the lack of direct support.

Enter Satsuma, a blockchain indexing platform with drop-in support for hosted subgraphs aimed at solving these challenges. In this guide, we'll cover how to add the Satsuma add-on to your QuickNode endpoint and then show you how to create, and deploy a subgraph using Satsuma. Let's get started!

Prefer a video walkthrough? Follow along with Radek and learn about subgraphs and how to deploy one using Satsuma in 25 minutes.
Subscribe to our YouTube channel for more videos!

What You Will Do

  • Learn about Satsuma
  • Add the Satsuma add-on to your QuickNode endpoint
  • Create, deploy, and manage a Subgraph using Satsuma

What You Will Need


What is Satsuma?

Satsuma is a hosted graph solution that allows developers to deploy and index subgraphs on a hosted service. Currently, if a network is not supported on The Graph's Hosted Service, you'll need to run your own graph node to index it. However, this can take extra engineering effort to set up and can be a mental burden to handle maintenance & issues. Satsuma solves this problem by allowing developers to quickly deploy subgraphs in less than 5 minutes.

Key Benefits of Satsuma

Features and key benefits of Satsuma include:

  • Reliability: 99.9% API SLA and lower data lag.
  • Speed: Up to 5x faster indexing and 2x faster queries.
  • Support: Telegram / Slack group with a team of engineers.
  • Developer tooling: Tools to save your engineering team time.

Additional features include advanced metrics & performance insights, subgraph versioning, and direct access to data in Postgres databases. In the future, Satsuma will also have support for GraphQL subscriptions and direct access to low-level decoded events.

In the next section, we'll cover how to add the Satsuma add-on to your QuickNode account and walkthrough the Satsuma dashboard.

Enable Satsuma on a QuickNode Endpoint


This add-on is no longer available for new installations. Only users who previously installed it can access and use it.

First, login to QuickNode (you can create a free account here), and then navigate to your endpoints. For this tutorial, you'll need an endpoint on Goerli Testnet. Create one now if you don't yet have one.

Once you have your Goerli Testnet endpoint set up, on your endpoint page, click the Add-ons tab and then click the Explore button on the Satsuma add-on. You'll see a pop-up box explaining pricing and which endpoints the add-on is compatible with. Once the add-on is enabled, you'll see it in your list of Installed Third-Party Add-Ons. With the add-on installed, click the Dashboard button to be directed to Satsuma's dashboard:

QuickNode / Satsuma Add-on Tab

Satsuma Dashboard:

Satsuma Demo Dashboard

The Satsuma dashboard above lets you quickly deploy subgraphs and create query keys. Query keys are similar to authentication tokens and allow you to conduct GraphQL queries. These query keys should be a part of your URL path (e.g.,<QUERY_KEY>/<ORGANIZATION>/<SUBGRAPH_NAME>/version/<VERSION_NAME>/api) or can be apart of your header (e.g., -H 'x-api-key: <QUERY_KEY>'). See the docs for a full example. An example use case for additional query keys is you can create a query key that allows origins from your domain(s) and has no rate limit (rate limiting coming soon).

In the following section, we'll show you how to create and deploy a subgraph on Satsuma.

Add and Deploy a Subgraph with Satsuma

Now, within your Satsuma dashboard, click the Add subgraph button and you'll be prompted with a graph-cli command. With this command, we can directly deploy a subgraph and host it with Satsuma.

graph deploy example-subgraph-name \
--version-label v0.0.1-new-version \
--node \
--deploy-key <DEPLOYER_KEY>

Note - As stated before, Satsuma also supports versioning, so you can deploy different subgraphs and subgraph versions. You can have up to 5 versions which all have a version-specific endpoint along with the production static endpoint.

Upon deployment, you'll see a similiar output too:

Satsuma Deployment Output

Now, navigate to the link highlighted in green. You'll see the the Satsuma subgraph page where you have access to the Playground, GraphQL API (HTTP), and Indexing Status.

Satsuma Subgraph

On the Playground page, you can make queries against your subgraph:

Satsuma Playground

You can also use the GraphQL API (HTTP) URL to make API requests:

Terminal cURL to Satsuma API

And check your Indexing Status:

Indexing Status

Final Thoughts

That's it! You know now how to create, deploy and manage your own subgraph using Satsuma. If you want to learn more, check out the following list of resources:

We would love to hear more about what you are building. Drop us a line in Discord, or give us a follow on Twitter to stay up to date on all the latest information!

We ❤️ Feedback!

Let us know if you have any feedback or requests for new topics. We'd love to hear from you.

Share this guide