Klayr Service

Klayr Service is a web application middleware that allows interaction with various blockchain networks based on the Klayr protocol.

The main focus of Klayr Service is to provide data to the UI clients such as Klayr Desktop. Klayr Service makes it possible to access all blockchain live data in a similar way to the regular Klayr SDK API, and in addition provides users with much more detailed in-depth information and endpoints, such as geolocation and various statistics regarding network usage.

The project implementation is based on Microservices. The technical stack is designed to deliver several microservices, and each of them provides one particular functionality. The data is served in JSON format and exposed by a public RESTful API, or a WebSocket-based RPC API.



Available Services

Klayr Service consists of various microservices which have been further expanded. Briefly, microservices can be defined as an architectural style that structures an application as a collection of small, loosely coupled services, whereby each service can run its own process, and offers the user the ability to reduce the complexity into more manageable services that can be developed, and deployed independently. The Gateway is required in order to expose the APIs provided by the specific services.

Each microservice is independently managed and is stored separately under the services directory. They contain their own package.json and Dockerfile that are beneficial for managing dependencies, and packaging a service into a containerized format, whereby it can be easily deployed, and managed in a distributed environment. To summarize, these benefits include various aspects such as dependency management, reproducible builds, containerization, versioning, and scalability.

An overview of each microservice is given in the following table listed below.


Table 1. The Klayr Service microservices
Microservice Description


The Gateway component exposes the API for Klayr Service users to access and use over HTTP and WS protocols. Its main purpose is to proxy API requests from users to other microservice components provided by Klayr Service. It provides the users with a central point of data access that ensures existing application compatibility is maintained.


The Blockchain Connector connects with the node running a Klayr protocol-compliant blockchain application. It is primarily responsible for data transformation and caching, hence reducing the number of calls made to the node.


The Blockchain Indexer contains both an indexer and data service mode. The indexer mode is mainly responsible for updating the index, based on the scheduled jobs by the Blockchain Coordinator. In the data service mode it serves user request queries initiated via the RESTful API or WebSocket-based RPC calls. It has the ability to run both the indexer and data service modes simultaneously, which is enabled by default.

App Registry

The Blockchain Application Registry service is responsible for regularly synchronizing and providing off-chain metadata information for known blockchain applications within the Klayr ecosystem. The metadata is maintained in the Klayr Application Registry repository.

Fee Estimator

The Fee Estimator service implements the dynamic fee system algorithm to offer users transaction fee recommendations based on the network traffic.

Transaction Statistics

The Transaction Statistics service computes various transaction statistics to offer users various real-time network insights.


The Market service allows price data retrieval. It supports multiple sources to maintain the current up-to-date Klayr token price, and ensures this is available to the clients in real time.


The Export service enables users to download the transaction history as a CSV file for any given account on the blockchain.


All Klayr Service services are derived from the Template service, which is an abstract microservice. It allows all services to share a similar interface and design pattern. The objective of the Template service is to reduce code duplication and increase consistency between each service, hence simplifying code maintenance and testing.

  • Klayr Service by default attempts to connect to a local node via WebSocket on port 7887 or IPC on ~/.klayr/klayr-core by default.

  • The default installation method is based on Docker.

  • Please note that certain token conversion rates in the Market service require their API keys.

  • For the events information to be always available in the API, please set the system.keepEventsForHeights: -1 in the Klayr application node config.

  • It is highly recommended NOT to enable any plugins on the Klayr application node when running Klayr Service against it. Enabling them can cause performance issues in Klayr Service.

The following diagram below depicts an overview of the microservice architecture. The inter-microservice communications are enabled with a message broker. This is generally an instance of Redis or NATS.

Microservices Architecture Overview

mservice architecture


The Gateway service provides the following APIs, which all users of Klayr Service can access and use.

Once Klayr Service is set up, configured, and started, it is possible to retrieve data from the blockchain network.

Klayr Service provides the data through several alternative APIs described below:


The HTTP API is the public RESTful API that provides blockchain data in standardized JSON format.

The HTTP API provides various endpoints that offer more extensive information in comparison to the HTTP API of that of a normal Klayr node. This API can be utilized to build powerful wallets and user interfaces for blockchain applications which are built with the Klayr SDK.

Public Klayr Service APIs

There is a public HTTP API for every public Klayr blockchain network, which can be used to query the desired information from the network.

Klayr Mainnet
Klayr Testnet

In the Public API base URLs listed above, in order to fetch the required entities it is necessary to add them at the end of the respective URL. e.g., /blocks, and /transactions, etc.

For example:

The WebSocket JSON-RPC API

The WebSocket JSON-RPC API provides blockchain data in standardized JSON format. The API uses the Socket.IO library and is compatible with JSON-RPC 2.0 standards. This enables efficient and seamless integration within the Klayr blockchain network, coupled with offering a more responsive, and efficient alternative to the traditional HTTP based APIs.

The RPC-API reference provides an overview of all available RPC requests. Almost every HTTP endpoint exposes a corresponding JSON-RPC endpoint to query over WebSocket. The only exception is the /export/download endpoint.

Klayr Mainnet
  • Public API: wss://service.klayr.xyz/rpc-v3

Klayr Testnet
  • Public API: wss://testnet-service.klayr.xyz/rpc-v3

The Subscribe API

The Subscribe API is an event-driven API that uses a two-way streaming connection, which can notify the client about new data instantly as it arrives. It is responsible for updating users regarding changes in the blockchain network and markets. The Subscribe API is particularly useful for providing the user with real-time data, e.g., real-time monitoring systems, notification services, and applications that need to react immediately to specific events that occur on the blockchain.

Check out the Publish/Subscribe API (Klayr Service) reference for an overview of all available RPC requests.
Klayr Mainnet
  • Public API: wss://service.klayr.xyz/blockchain

Klayr Testnet
  • Public API: wss://testnet-service.klayr.xyz/blockchain