Skip to content

Sidecar API

View page in Markdown Download page in Markdown Open in ChatGPT Open in Claude

Introduction

Section titled “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.

Prerequisites

Section titled “Prerequisites”

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

Terminal window
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.

Installation

Section titled “Installation”

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

Terminal window
npm install -g @substrate/api-sidecar

You can confirm the installation by running:

Terminal window
substrate-api-sidecar --version

For more information about the Sidecar API installation, see the installation and usage section of the Sidecar API README.

Usage

Section titled “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 the following:

    Terminal window
    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.

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

    For more configuration details, see 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

Section titled “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:

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

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

Section titled “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.

Last updated: