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
- Rate Control
- Inner Retry Mechanism upon Timeouts
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 | |
| Get historical tokenomic stats | Get the circulating utxo, treasury, rewards, supply and reserves in lovelace for specified epoch, all epochs if empty | |
| 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 | |
| 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 | |
| Transactions | Transaction Information | Get detailed information about transaction(s) |
| Transaction UTxOs | Get UTxO set (inputs/outputs) of transactions. | |
| 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 Transactions | Get the transaction hash list of input address 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 | |
| Transactions from payment credentials | Get the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive) | |
| Account | Account List | Get a list of all accounts |
| Account Information | Get the account info of any (payment or staking) address | |
| 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) |
| Asset Address List | Get the list of all addresses holding a given asset | |
| Asset Information | Get the information of an asset including first minting & token registry metadata | |
| Asset History | Get the mint/burn history of an asset | |
| Asset Policy Information | Get the information for all assets under the same policy | |
| Asset Summary | Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) | |
| Asset Transaction History | 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 Delegators List | Return information about delegators by a given pool and optional epoch (current if omitted) | |
| 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 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 | 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 |
Version Compatability Chart
| Koios Instance | Koios Java Client |
|---|---|
| 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.13</version>
</dependency>- For Gradle, add the following dependency to build.gradle
compile group: 'io.github.cardano-community', name: 'koios-java-client', version: '1.13'
- Mainnet
BackendService backendService = BackendFactory.getKoiosMainnetService();- Testnet
BackendService backendService = BackendFactory.getKoiosTestnetService();- Guildnet
BackendService backendService = BackendFactory.getKoiosGuildService();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. #3168087 to Block No. #3168097 (inclusive), Limited to Maximum of 10 Results.
String address = "addr_test1qzx9hu8j4ah3auytk0mwcupd69hpc52t0cw39a65ndrah86djs784u92a3m5w475w3w35tyd6v3qumkze80j8a6h5tuqq5xe8y";
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, "3168087"))
.option(Filter.of("block_height", FilterType.LTE, "3168097")).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) | 60 |
| KOIOS_JAVA_LIB_CONNECT_TIMEOUT_SEC | integer | Sets the default connect timeout for new connections (seconds) | 60 |
git clone https://github.com/cardano-community/koios-java-client.git
cd koios-java-client
mvn clean install