Substrate / Polkadot indexer template (Squid SDK)

July 27, 2026 · View on GitHub

A starter Squid project to demonstrate its structure and conventions. It accumulates kusama account transfers and serves them via GraphQL API.

Accessing the SQD Network gateway

This squid sources historical data from the SQD Network v2 gateway (https://v2.archive.subsquid.io/network/kusama). Since May 19, 2026, self-hosted squids need an API key to access these gateways (see SQD API keys):

  1. Create a key at portal.sqd.dev/app.

  2. Add it to .env: SQD_API_KEY=your_api_key.

  3. Pass it to the .setGateway(...) call in src/processor.ts:

    .setGateway({
    url: 'https://v2.archive.subsquid.io/network/kusama',
    apiKey: process.env.SQD_API_KEY,
})

Squids deployed to SQD Cloud don't need this — the platform provides gateway access.

Documentation

Summary

Prerequisites

  • Node.js 20 or newer
  • docker
  • npm -- note that yarn package manager is not supported

Quickly running the sample

Example commands below use sqd. Please install it before proceeding.

# 1. Install dependencies
npm i

# 2. Start target Postgres database and detach
sqd up

# 3. Build the project
sqd build

# 4. Start both the squid processor and the GraphQL server
sqd run .

A GraphiQL playground will be available at localhost:4350/graphql.

SQD Network gateways for Parachains

SQD provides gateway (archive) data sources for most parachains. Point the processor at one with .setGateway(<url>), as done in src/processor.ts:

processor.setGateway('https://v2.archive.subsquid.io/network/kusama')

The gateway supplies historical data; .setRpcEndpoint(...) is still required on Substrate for chain metadata and real-time updates. Browse the available network URLs on the Substrate networks page.

If the chain is not yet supported, you can still index it from RPC alone (drop .setGateway(...) and keep .setRpcEndpoint(...)); see the processor reference. If you take this route, use the metadata explorer with Substrate typegen for help with decoding.

You can also fill out this form to submit a request for an SQD Network dataset.

Dev flow

1. Define database schema

Start development by defining the schema of the target database via schema.graphql. Schema definition consists of regular graphql type declarations annotated with custom directives. Full description of schema.graphql dialect is available here.

2. Generate TypeORM classes

Mapping developers use TypeORM entities to interact with the target database during data processing. All necessary entity classes are generated by the squid framework from schema.graphql. This is done by running npx squid-typeorm-codegen or (equivalently) sqd codegen command.

3. Generate database migration

All database changes are applied through migration files located at db/migrations. squid-typeorm-migration(1) tool provides several commands to drive the process. It is all TypeORM under the hood.

# Connect to database, analyze its state and generate migration to match the target schema.
# The target schema is derived from entity classes generated earlier.
# Don't forget to compile your entity classes beforehand!
npx squid-typeorm-migration generate

# Create template file for custom database changes
npx squid-typeorm-migration create

# Apply database migrations from `db/migrations`
npx squid-typeorm-migration apply

# Revert the last performed migration
npx squid-typeorm-migration revert

Available sqd shortcuts:

# Build the project, remove any old migrations, then run `npx squid-typeorm-migration generate`
sqd migration:generate

# Run npx squid-typeorm-migration apply
sqd migration:apply

4. Generate TypeScript definitions for substrate events, calls and storage

This is an optional part, but it is very advisable.

Event, call and runtime storage data come to mapping handlers as raw untyped json. While it is possible to work with raw untyped json data, it's extremely error-prone and the json structure may change over time due to runtime upgrades.

Squid framework provides a tool for generating type-safe wrappers around events, calls and runtime storage items for each historical change in the spec version. See the Substrate typegen documentation page.

Deploy the Squid

After a local run, obtain a deployment key by signing into SQD Cloud and run

npx sqd auth -k YOUR_DEPLOYMENT_KEY

Next, inspect the Squid CLI help to deploy and manage your squid:

npx sqd squid --help

For more information, consult the Deployment Guide.

Project conventions

Squid tools assume a certain project layout.

  • All compiled js files must reside in lib and all TypeScript sources in src. The layout of lib must reflect src.
  • All TypeORM classes must be exported by src/model/index.ts (lib/model module).
  • Database schema must be defined in schema.graphql.
  • Database migrations must reside in db/migrations and must be plain js files.
  • squid-*(1) executables consult .env file for a number of environment variables.

See the full description in the documentation.

Types bundle

Substrate chains that have blocks with metadata versions below 14 don't provide enough information to decode their data. For those chains, external type definitions are required.

SQD tools include definitions for many chains, however sometimes external definitions are still required.

You can pass them as a special json file (types bundle) of the following structure:

{
  "types": {
    "AccountId": "[u8; 32]"
  },
  "typesAlias": {
    "assets": {
      "Balance": "u64"
    }
  },
  "versions": [
    {
      "minmax": [0, 1000], // spec version range with inclusive boundaries
      "types": {
        "AccountId": "[u8; 16]"
      },
      "typesAlias": {
        "assets": {
          "Balance": "u32"
        }
      }
    }
  ]
}

All fields in the type bundle are optional and applied on top of a fixed set of well-known frame types.

Note, that although the structure of SQD types bundle is very similar to the one from polkadot.js, those two are not fully compatible.

Differences from polkadot.js

Polkadot.js provides lots of specialized classes for various types of data. Even primitives like u32 are exposed through special classes. In contrast, the squid framework works only with plain js primitives and objects. For instance, account data is passed to the handler context as a plain byte array. To convert it into a standard human-readable format one should explicitly use a utility lib @subsquid/ss58:

    // ...
    from: ss58.codec('kusama').encode(rec.from),
    to: ss58.codec('kusama').encode(rec.to),

Graphql server extensions

It is possible to extend squid-graphql-server(1) with custom type-graphql resolvers and to add request validation. For more details, consult docs.