https://github.com/cardano-community/koios-java-client
koios-java-client
https://github.com/cardano-community/koios-java-client
api-client blockchain cardano java transaction
Last synced: 12 days ago
JSON representation
koios-java-client
- Host: GitHub
- URL: https://github.com/cardano-community/koios-java-client
- Owner: cardano-community
- License: apache-2.0
- Created: 2022-01-20T11:52:32.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-05-07T06:43:03.000Z (about 1 year ago)
- Last Synced: 2024-08-03T18:14:56.351Z (10 months ago)
- Topics: api-client, blockchain, cardano, java, transaction
- Language: Java
- Homepage: https://www.koios.rest/
- Size: 761 KB
- Stars: 18
- Watchers: 8
- Forks: 3
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
## What is Koios?
**Koios** Java Client Library is based on [Koios](https://www.koios.rest/) Elastic Query Layer for [Cardano Node](https://github.com/input-output-hk/cardano-node/) by [Cardano Community Guild Operators](https://github.com/cardano-community).
**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
CLI Protocol Parameters
Get Current Protocol Parameters as published by cardano-cli.
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 (Raw CBOR)
Get raw CBOR data for all transaction(s) within 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
Address Outputs
Basic transaction output info 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 Reward History
Get the full rewards history (including MIR) for a stake address, or certain epoch if specified
Account Update History
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 Stake 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 (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 Voting Power History
History of DReps voting power against each (or requested) epoch
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
Vote List
List of all votes posted on-chain
Pool's Voting Power History
History of Pool voting power against each (or requested) epoch
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 Owner History
List of Cardano pool IDs (bech32 format)
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 Groups
List of all registered pool and their groups across sources from pool_groups repository. This is only relevant for mainnet
Pool Metadata
Metadata (on & off-chain) for all currently registered/retiring (not retired) pools
Pool Calidus Keys
List of valid calidus keys for all 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.3.2 | 1.21.0 |
| 1.3.0 | 1.20.1 |
| 1.2.0 | 1.19.3 |
| 1.1.2 | 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 |
## Use as a library in a Java Project
### Add dependency
- For Maven, add the following dependency to project's pom.xml
```xml
io.github.cardano-community
koios-java-client
1.21.0
```
- For Gradle, add the following dependency to build.gradle
```
compile group: 'io.github.cardano-community', name: 'koios-java-client', version: '1.21.0'
```
### Get Koios Backend Service (No API Token)
- Mainnet
```java
BackendService backendService = BackendFactory.getKoiosMainnetService();
```
- Preview
```java
BackendService backendService = BackendFactory.getKoiosPreviewService();
```
- Preprod
```java
BackendService backendService = BackendFactory.getKoiosPreprodService();
```
- Guildnet
```java
BackendService backendService = BackendFactory.getKoiosGuildService();
```
### Get Koios Backend Service (with API Token)
Get Your API Token from Koios Website: https://www.koios.rest/
- Mainnet
```java
String apiToken = "";
BackendService backendService = BackendFactory.getKoiosMainnetService(apiToken);
```
### Get Koios Backend Services
```java
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.
```java
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> transactionsResult = addressService.getAddressTransactions(List.of(address), options);
```
### Supported Environment Variables
| 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 |
## Clone & Build with Maven
```shell
git clone https://github.com/cardano-community/koios-java-client.git
cd koios-java-client
mvn clean install
```
## Used by
* [Bloxbean - Cardano Client Library](https://github.com/bloxbean/cardano-client-lib)
* [ISR - Israeli Cardano Community](https://www.cardano-israel.com/)
* [MusicBox - CNFT Project](https://www.musicboxnft.com/)
* [Adabox - Decentralized All in One Hub](https://adabox.io/)
:triangular_ruler: Contributing
|
:gift_heart: Sponsors
|
Discord (#koios-java-client)