koios-java-client

koios-java-client copied to clipboard

What is Koios?

Koios Java Client Library is based on Koios Elastic Query Layer for Cardano Node by Cardano Community Guild Operators.
Koios is best described as a Decentralized and Elastic RESTful query layer for exploring data on Cardano blockchain to consume within applications/wallets/explorers/etc.
Resource and maintenance requirements for Cardano blockchain components (e.g. cardano-node, cardano-db-sync) are ever-growing. Along with that, every builder needs to identify how to query complex information from the chain.

Overview

Koios Java Client is a Java REST Client library which allows interacting with Koios Server Instances using Java Objects.

Features

• Synchronous REST messaging using java objects
• Structured Java Objects logging
• Pagination (Limit and Offset) Supported
• Horizontal Filtering Supported
• Sorting Supported
• API Token Supported
• Inner Retry Mechanism upon Timeouts
• HTTP GZIP Compression Supported

Use as a library in a Java Project

Add dependency

• For Maven, add the following dependency to project's pom.xml

<dependency>
    <groupId>io.github.cardano-community</groupId>
    <artifactId>koios-java-client</artifactId>
    <version>1.18.2</version>
</dependency>

• For Gradle, add the following dependency to build.gradle

compile group: 'io.github.cardano-community', name: 'koios-java-client', version: '1.18.2'

Get Koios Backend Service (No API Token)

• Mainnet

BackendService backendService = BackendFactory.getKoiosMainnetService();

• Preview

BackendService backendService = BackendFactory.getKoiosPreviewService();

• Preprod

BackendService backendService = BackendFactory.getKoiosPreprodService();

• Guildnet

BackendService backendService = BackendFactory.getKoiosGuildService();

Get Koios Backend Service (with API Token)

Get Your API Token from Koios Website: https://www.koios.rest/

• Mainnet

String apiToken = "<API_TOKEN>";
BackendService backendService = BackendFactory.getKoiosMainnetService(apiToken);

Get Koios Backend Services

NetworkService networkService = backendService.getNetworkService();
EpochService epochService = backendService.getEpochService();
BlockService blockService = backendService.getBlockService();
TransactionsService transactionsService = backendService.getTransactionsService();
AddressService addressService = backendService.getAddressService();
AccountService accountService = backendService.getAccountService();
AssetService assetService = backendService.getAssetService();
PoolService poolService = backendService.getPoolService();
ScriptService scriptService = backendService.getScriptService();

Advanced Query Example (Preview)

Querying a Descending Order of All Address Transactions since Block No. #42248 to Block No. #69447 (inclusive), Limited to Maximum of 10 Results.

String address = "addr_test1qrvaadv0h7atv366u6966u4rft2svjlf5uajy8lkpsgdrc24rnskuetxz2u3m5ac22s3njvftxcl2fc8k8kjr088ge0qz98xmv";

Options options = Options.builder()
        .option(Limit.of(10))
        .option(Offset.of(0))
        .option(Order.by("block_height", SortType.DESC))
        .option(Filter.of("block_height", FilterType.GTE, "42248"))
        .option(Filter.of("block_height", FilterType.LTE, "69447")).build();

Result<List<TxHash>> transactionsResult = addressService.getAddressTransactions(List.of(address), options);

Supported Environment Variables

Clone & Build with Maven

git clone https://github.com/cardano-community/koios-java-client.git
cd koios-java-client
mvn clean install

Used by

• Bloxbean - Cardano Client Library
• ISR - Israeli Cardano Community
• MusicBox - CNFT Project
• Adabox - Decentralized All in One Hub

:triangular_ruler: Contributing | :gift_heart: Sponsors | Discord (#koios-java-client)