Quickstart - SQD Documentation

This 5-minute tutorial shows you how to grab a Substrate Squid SDK indexer template. At the end you’ll have a complete blockchain indexer that fetches, decodes, and serves KSM transfers data from Kusama.

What you’ll get

Your Substrate indexer (squid) will:

Fetch all historical KSM transfers on Kusama
Save the data to a local PostgreSQL database
Start a GraphQL server with a rich API to query the indexed transfers

This tutorial focuses on Substrate. For other chains, see the EVM Quickstart or Solana Quickstart.

Prerequisites

Before you begin, ensure you have:

Node.js v20+ - Download here
Git - Download here
Docker - Download here (for running PostgreSQL)
WSL (Windows only) - Install WSL

(Optional) Install Squid CLI

Install the Squid CLI globally:

npm i -g @subsquid/cli@latest

Verify installation by running sqd --version

Squid CLI is a multi-purpose utility tool for scaffolding and managing indexers, both locally and in SQD Cloud.

Scaffold the indexer project

Create a new squid project from the substrate template:

sqd init hello-squid -t substrate
cd hello-squid

or, if you skipped the installation of Squid CLI

git clone https://github.com/subsquid-labs/squid-substrate-template hello-squid
cd hello-squid

Inspect the project structure

Explore the project structure:

hello-squid

scripts

src

main.ts

model

generated

index.ts

processor.ts

types

.env

.squidignore

commands.json

docker-compose.yml

package.json

schema.graphql

squid.yaml

tsconfig.json

typegen.json

src/processor.ts: the data retrieval configuration.
src/main.ts: the main executable, with the processing logic.
src/types/: modules generated from typegen.json for interfacing the balances pallet data.
src/model/: TypeORM model classes used in database operations. The classes in src/model/generated/ are generated from schema.graphql.

The processor.ts file defines the SubstrateBatchProcessor object and configures data retrieval:

processor.ts

export const processor = new SubstrateBatchProcessor()
  // SQD gateway is the faster source of historical data.
  .setGateway({
    url: 'https://v2.archive.subsquid.io/network/kusama',
    apiKey: process.env.SQD_API_KEY,
  })
  // Chain RPC endpoint is required on Substrate for metadata and real-time updates
  .setRpcEndpoint({
    // Set via .env for local runs or via secrets when deploying to Subsquid Cloud
    // https://docs.subsquid.io/deploy-squid/env-variables/
    url: assertNotNull(process.env.RPC_KUSAMA_HTTP, 'No RPC endpoint supplied'),
    // More RPC connection options at https://docs.subsquid.io/substrate-indexing/setup/general/#set-data-source
    rateLimit: 10
  })
  .addEvent({
    name: [events.balances.transfer.name],
    extrinsic: true
  })
  .setFields({
    event: {
      args: true
    },
    extrinsic: {
      hash: true,
      fee: true
    },
    block: {
      timestamp: true
    }
  })

Next, main.ts defines the data processing and storage logic. Data processing is defined in the batch handler, the callback that the processor.run() main call receives as its final argument:

main.ts

processor.run(new TypeormDatabase({supportHotBlocks: true}), async (ctx) => {
  let transferEvents: TransferEvent[] = getTransferEvents(ctx)

  let accounts: Map<string, Account> = await createAccounts(ctx, transferEvents)
  let transfers: Transfer[] = createTransfers(transferEvents, accounts)

  await ctx.store.upsert([...accounts.values()])
  await ctx.store.insert(transfers)
})

See the full file for details.

Install dependencies and build

Install dependencies and build the project:

npm i
npm install @subsquid/substrate-processor@latest
npm install --save-dev @subsquid/substrate-typegen@latest
npm run build

Verify the build completed successfully by checking for the lib/ directory.

Start the database and processor

The processor continuously fetches data, decodes it, and stores it in PostgreSQL. All logic is defined in main.ts and is fully customizable.Add your SQD Network API key to .env before starting the processor:

SQD_API_KEY=<YOUR_SQD_NETWORK_API_KEY>

First, start a local PostgreSQL database (the template includes a Docker Compose file):

docker compose up -d

The processor connects to PostgreSQL using connection parameters from .env. Ensure the database is running before proceeding.

Apply database migrations:

npx squid-typeorm-migration apply

Then start the processor:

node -r dotenv/config lib/main.js

The indexer is now running and will begin processing blocks.

Start the GraphQL API

Start the GraphQL API to serve the transfer data:

npx squid-graphql-server

Query the data

You can now query your indexed data! Check it out at the GraphiQL playground at localhost:4350/graphql.

​What you’ll get

​Prerequisites

What you’ll get

Prerequisites