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
  Supported REST Services

  Service	Endpoint	Description
  Network	Chain Tip	Get the tip info about the latest block seen by chain
  	Genesis Info	Get the Genesis parameters used to start specific era on chain
  	Historical tokenomic stats	Get the circulating utxo, treasury, rewards, supply and reserves in lovelace for specified epoch, all epochs if empty
  	Param Update Proposals	Get all parameter update proposals submitted to the chain starting Shelley era
  	Reserve Withdrawals	List of all withdrawals from reserves against stake accounts
  	Treasury Withdrawals	List of all withdrawals from treasury against stake accounts
  Epoch	Epoch Information	Get the epoch information, all epochs if no epoch specified
  	Epoch's Protocol Parameters	Get the protocol parameters for specific epoch, returns information about all epochs if no epoch specified
  	Epoch's Block Protocols	Get the information about block protocol distribution in epoch
  Block	Block List	Get summarised details about all blocks (paginated - latest first)
  	Block Information	Get detailed information about a specific block
  	Block Transactions	Get a list of all transactions included in a provided block
  	Block Transactions (Detailed Info)	Get detailed information about transaction(s) for requested blocks
  Transactions	UTxO Info	Get UTxO set for requested UTxO references
  	Raw Transaction (CBOR)	Get raw transaction(s) in CBOR format
  	Transaction Information	Get detailed information about transaction(s)
  	Transaction Metadata	Get metadata information (if any) for given transaction(s)
  	Transaction Metadata Labels	Get a list of all transaction metalabels
  	Submit Transaction	Submit an already serialized transaction to the network.
  	Transaction Status (Block Confirmations)	Get the number of block confirmations for a given transaction hash list
  Address	Address Information	Get address info - balance, associated stake address (if any) and UTxO set
  	Address UTxOs	Get UTxO set for given addresses
  	UTxOs from payment credentials	Get UTxO details for requested payment credentials
  	Address Transactions	Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive)
  	Transactions from payment credentials	Get the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive)
  	Address Assets	Get the list of all the assets (policy, name and quantity) for a given address
  Stake Account	Account List	Get a list of all accounts
  	Account Information	Get the account info of any (payment or staking) address
  	Account Information (Cached)	Get the cached account information for given stake addresses (accounts)
  	Account UTxOs	Get a list of all UTxOs for given stake addresses (account)s
  	Account Txs	Get a list of all Txs for a given stake address (account)
  	Account Rewards	Get the full rewards history (including MIR) for a stake address, or certain epoch if specified
  	Account Updates	Get the account updates (registration, deregistration, delegation and withdrawals)
  	Account Addresses	Get all addresses associated with an account
  	Account Assets	Get the native asset balance of an account
  	Account History	Get the staking history of an account
  Asset	Asset List	Get the list of all native assets (paginated)
  	Policy Asset List	Get the list of asset under the given policy (including balances)
  	Asset Token Registry	Get a list of assets registered via token registry on github
  	Asset Information	Get the information of an asset including first minting & token registry metadata
  	Asset Information (Bulk)	Get the information of a list of assets including first minting & token registry metadata
  	Asset UTxOs	Get the UTXO information of a list of assets including
  	Asset History	Get the mint/burn history of an asset
  	Asset Addresses	Get the list of all addresses holding a given asset
  	NFT Address	Get the address where specified NFT currently reside on
  	Policy Asset Address List	Get the list of addresses with quantity for each asset on the given policy.
  	Policy Asset Information	Get the information for all assets under the same policy
  	Policy Asset Mints	Get a list of mint or burn count details for all assets minted under a policy
  	Asset Summary	Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance)
  	Asset Transactions	Get the list of all asset transaction hashes (newest first)
  Governance	DReps Epoch Summary	Summary of voting power and DRep count for each epoch
  	DReps List	List of all active delegated representatives (DReps)
  	DReps Info	Get detailed information about requested delegated representatives (DReps)
  	DReps Metadata	List metadata for requested delegated representatives (DReps)
  	DReps Updates	List of updates for requested (or all) delegated representatives (DReps)
  	DReps Votes	List of all votes casted by requested delegated representative (DRep)
  	DReps Delegators	List of all delegators to requested delegated representative (DRep).
  	Committee Information	Information about active committee and its members
  	Committee Votes	List of all votes casted by given committee member or collective
  	Proposals List	List of all governance proposals
  	Voter's Proposal List	List of all governance proposals for specified DRep, SPO or Committee credential
  	Proposal Voting Summary	Summary of votes for given proposal
  	Proposal Votes	List of all votes cast on specified governance action
  	Pool Votes	List of all votes casted by a pool
  Pool	Pool List	A list of all currently registered/retiring (not retired) pools
  	Pool Information	Current pool statuses and details for a specified list of pool ids
  	Pool Stake Snapshot	Returns Mark, Set and Go stake snapshots for the selected pool, useful for leaderlog calculation
  	Pool Delegators List	Return information about live delegators for a given pool.
  	Pool Delegators History	Return information about active delegators (incl. history) for a given pool and epoch number - current epoch if not provided.
  	Pool Blocks	Return information about blocks minted by a given pool in current epoch (or _epoch_no if provided)
  	Pool Stake, Block and Reward History	Return information about pool stake, block and reward history in a given epoch _epoch_no (or all epochs that pool existed for, in descending order if no _epoch_no was provided)
  	Pool Updates (History)	Return all pool updates for all pools or only updates for specific pool if specified
  	Pool Registrations	Return all pool registrations initiated in the requested epoch
  	Pool Retirements	Return all pool retirements initiated in the requested epoch
  	Pool Relays	A list of registered relays for all currently registered/retiring (not retired) pools
  	Pool Metadata	Metadata (on & off-chain) for all currently registered/retiring (not retired) pools
  Script	Script Information	List of script information for given script hashes
  	Native Script List	List of all existing native script hashes along with their creation transaction hashes
  	Plutus Script List	List of all existing Plutus script hashes along with their creation transaction hashes
  	Script Redeemers	List of all redeemers for a given script hash
  	Script UTxOs	List of all UTXOs for a given script hash
  	Datum Information	List of datum information for given datum hashes

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.19.3</version>
  </dependency>

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

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

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)