Skip to content

Sidecar API

Introduction

The Sidecar Rest API is a service that provides a REST interface for interacting with Polkadot SDK-based blockchains. With this API, developers can easily access a broad range of endpoints for nodes, accounts, transactions, parachains, and more.

Sidecar functions as a caching layer between your application and a Polkadot SDK-based node, offering standardized REST endpoints that simplify interactions without requiring complex, direct RPC calls. This approach is especially valuable for developers who prefer REST APIs or build applications in languages with limited WebSocket support.

Some of the key features of the Sidecar API include:

  • REST API interface - provides a familiar REST API interface for interacting with Polkadot SDK-based chains
  • Standardized endpoints - offers consistent endpoint formats across different chain implementations
  • Caching layer - acts as a caching layer to improve performance and reduce direct node requests
  • Multiple chain support - works with any Polkadot SDK-based chain, including Polkadot, Kusama, and custom chains

Installation

To install Substrate API Sidecar, use one of the following commands:

npm install -g @substrate/api-sidecar

pnpm install -g @substrate/api-sidecar

yarn global add @substrate/api-sidecar

Note

Sidecar API requires Node.js version 18.14 LTS or higher. Verify your Node.js version:

node --version

If you need to install or update Node.js, visit the official Node.js website to download and install the latest LTS version.

You can confirm the installation by running:

substrate-api-sidecar --version

For more information about the Sidecar API installation, please refer to the official documentation.

Usage

To use the Sidecar API, you have two options:

  • Local node - run a node locally, which Sidecar will connect to by default, requiring no additional configuration. To start, run: 
    substrate-api-sidecar

  • Remote node - connect Sidecar to a remote node by specifying the RPC endpoint for that chain. For example, to gain access to the Polkadot Asset Hub associated endpoints: 

    SAS_SUBSTRATE_URL=wss://polkadot-asset-hub-rpc.polkadot.io substrate-api-sidecar

    Note

    More configuration details are available in the Configuration section of the Sidecar API documentation.

Once the Sidecar API is running, you’ll see output similar to this:

SAS_SUBSTRATE_URL=wss://polkadot-asset-hub-rpc.polkadot.io substrate-api-sidecar
SAS: 📦 LOG: ✅ LEVEL: "info" ✅ JSON: false ✅ FILTER_RPC: false ✅ STRIP_ANSI: false ✅ WRITE: false ✅ WRITE_PATH: "/opt/homebrew/lib/node_modules/@substrate/api-sidecar/build/src/logs" ✅ WRITE_MAX_FILE_SIZE: 5242880 ✅ WRITE_MAX_FILES: 5 📦 SUBSTRATE: ✅ URL: "wss://polkadot-asset-hub-rpc.polkadot.io" ✅ TYPES_BUNDLE: undefined ✅ TYPES_CHAIN: undefined ✅ TYPES_SPEC: undefined ✅ TYPES: undefined ✅ CACHE_CAPACITY: undefined 📦 EXPRESS: ✅ BIND_HOST: "127.0.0.1" ✅ PORT: 8080 ✅ KEEP_ALIVE_TIMEOUT: 5000 📦 METRICS: ✅ ENABLED: false ✅ PROM_HOST: "127.0.0.1" ✅ PROM_PORT: 9100 ✅ LOKI_HOST: "127.0.0.1" ✅ LOKI_PORT: 3100 ✅ INCLUDE_QUERYPARAMS: false
2024-11-06 08:06:01 info: Version: 19.3.0 2024-11-06 08:06:02 warn: API/INIT: RPC methods not decorated: chainHead_v1_body, chainHead_v1_call, chainHead_v1_continue, chainHead_v1_follow, chainHead_v1_header, chainHead_v1_stopOperation, chainHead_v1_storage, chainHead_v1_unfollow, chainHead_v1_unpin, chainSpec_v1_chainName, chainSpec_v1_genesisHash, chainSpec_v1_properties, transactionWatch_v1_submitAndWatch, transactionWatch_v1_unwatch, transaction_v1_broadcast, transaction_v1_stop 2024-11-06 08:06:02 info: Connected to chain Polkadot Asset Hub on the statemint client at wss://polkadot-asset-hub-rpc.polkadot.io 2024-11-06 08:06:02 info: Listening on http://127.0.0.1:8080/ 2024-11-06 08:06:02 info: Check the root endpoint (http://127.0.0.1:8080/) to see the available endpoints for the current node

With Sidecar running, you can access the exposed endpoints via a browser, Postman, curl, or your preferred tool.

Endpoints

Sidecar API provides a set of REST endpoints that allow you to query different aspects of the chain, including blocks, accounts, and transactions. Each endpoint offers specific insights into the chain’s state and activities.

For example, to retrieve the version of the node, use the /node/version endpoint:

curl -X 'GET' \
  'http://127.0.0.1:8080/node/version' \
  -H 'accept: application/json'

Note

Alternatively, you can access http://127.0.0.1:8080/node/version directly in a browser since it’s a GET request.

In response, you’ll see output similar to this (assuming you’re connected to Polkadot Asset Hub):

curl -X 'GET' 'http://127.0.0.1:8080/node/version' -H 'accept: application/json'
{ "clientVersion": "1.16.1-835e0767fe8", "clientImplName": "statemint", "chain": "Polkadot Asset Hub" }

For a complete list of available endpoints and their documentation, visit the Sidecar API list endpoints. You can learn about the endpoints and how to use them in your applications.

Where to Go Next

To dive deeper, refer to the official Sidecar documentation. This provides a comprehensive guide to the available configurations and advanced usage.

Edit this page
Last update: November 12, 2024
| Created: October 18, 2024