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.
Koios Java Client is a Java REST Client library which allows interacting with Koios Server Instances using Java Objects.
- 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 |
| 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) | |
| 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 |
Version Compatability Chart
| Koios Instance | Koios Java Client |
|---|---|
| 1.1.1 | 1.18.2 |
| 1.0.10 | 1.17.3 |
| 1.0.9 | 1.16.3 |
| 1.0.8 | 1.15.2 |
| 1.0.7 | 1.14.1 |
| 1.0.6 | 1.13 |
- 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'
- Mainnet
BackendService backendService = BackendFactory.getKoiosMainnetService();- Preview
BackendService backendService = BackendFactory.getKoiosPreviewService();- Preprod
BackendService backendService = BackendFactory.getKoiosPreprodService();- Guildnet
BackendService backendService = BackendFactory.getKoiosGuildService();Get Your API Token from Koios Website: https://www.koios.rest/
- Mainnet
String apiToken = "<API_TOKEN>";
BackendService backendService = BackendFactory.getKoiosMainnetService(apiToken);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();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);| Variable | Type | Description | Default |
|---|---|---|---|
| KOIOS_JAVA_LIB_LOGGING | boolean | Toggle Logging | false |
| KOIOS_JAVA_LIB_RETRIES_COUNT | integer | Sets the max retry count upon request timeout | 5 |
| KOIOS_JAVA_LIB_READ_TIMEOUT_SEC | integer | Sets the default read timeout for new connections (seconds) | 300 |
| KOIOS_JAVA_LIB_CONNECT_TIMEOUT_SEC | integer | Sets the default connect timeout for new connections (seconds) | 300 |
| KOIOS_JAVA_LIB_RETRY_ON_TIMEOUT | boolean | Sets whether to retry upon request timeout | true |
| KOIOS_JAVA_LIB_GZIP_COMPRESSION | boolean | Sets whether to use GZIP Compression | true |
git clone https://github.com/cardano-community/koios-java-client.git
cd koios-java-client
mvn clean install- Bloxbean - Cardano Client Library
- ISR - Israeli Cardano Community
- MusicBox - CNFT Project
- Adabox - Decentralized All in One Hub
Discord (#koios-java-client)