Maestro Java Client

What is Maestro?

Maestro is a powerful blockchain indexer for the Cardano blockchain that provides a comprehensive REST API for accessing blockchain data. Maestro offers high-performance, reliable access to on-chain data with minimal latency.

Overview

Maestro Java Client is a Java REST Client library that provides type-safe access to the Maestro blockchain indexer APIs for Cardano. This library allows developers to interact with Cardano blockchain data using well-structured Java objects and handles all the complexities of HTTP communication, serialization, and error handling.

Features

• 🚀 Type-safe API access with strongly-typed models
• 📄 Built-in pagination support with flexible query options
• 🔧 Comprehensive error handling and retry mechanisms
• 🗜️ GZIP compression support for improved performance
• ⚙️ Configurable timeouts and retry policies
• 🌐 Multi-network support (Mainnet, Preprod, Preview)
• 📊 Complete API coverage for all Maestro endpoints
• 🛡️ Bean validation support
• 📝 Extensive documentation and examples

Supported Services

Comprehensive list of supported Maestro APIs

Service Category	Endpoints	Description
Accounts	/accounts/*	Stake account information, rewards, history, delegations
Addresses	/addresses/*	Address details, UTXOs, transactions
Assets	/assets/*	Native assets, tokens, NFTs metadata
Blocks	/blocks/*	Block information, transactions
Datum	/datum/*	Script datum values
DEX	/dex/*	Decentralized exchange data
Epochs	/epochs/*	Epoch information, parameters
General	/general/*	Chain info, protocol parameters
Pools	/pools/*	Stake pool information, delegators
Policies	/policies/*	Minting policies, assets
Scripts	/scripts/*	Smart contract scripts
Transactions	/transactions/*	Transaction details, submission

Version Compatibility

Library Version	Maestro API	Java Version	Status
1.0.0+	v1	11+	✅ Active

Library Usage

Add Dependency

Maven

<dependency>
    <groupId>io.github.gero-labs</groupId>
    <artifactId>maestro-java-client</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'io.github.gero-labs:maestro-java-client:1.0.0'

Initialize Maestro Service

Simple Initialization

import adlabs.maestro.client.backend.factory.BackendFactory;
import adlabs.maestro.client.backend.factory.BackendService;

// Initialize for Mainnet
String apiKey = "your-maestro-api-key";
BackendService maestroService = BackendFactory.getMaestroMainnetService(apiKey);

// Initialize for Preprod
BackendService maestroPreprodService = BackendFactory.getMaestroPreprodService(apiKey);

// Initialize for Preview
BackendService maestroPreviewService = BackendFactory.getMaestroPreviewService(apiKey);

Example Usage

Get Account Information

import adlabs.maestro.client.backend.api.account.model.TimestampedAccountInfo;
import adlabs.maestro.client.backend.api.base.Result;
import adlabs.maestro.client.backend.factory.options.Options;

// Get account information
String stakeAddress = "stake1u9ylzsgxaa6xctf4juup682ar3juj85n8tx3hthnljg47zctvm3rc";
Result<TimestampedAccountInfo> result = maestroService.getAccountService()
    .getAccountInfo(stakeAddress, Options.EMPTY);

if (result.isSuccessful()) {
    TimestampedAccountInfo accountInfo = result.getValue();
    System.out.println("Total Balance: " + accountInfo.getData().getTotalBalance());
    System.out.println("Rewards: " + accountInfo.getData().getRewardsAvailable());
} else {
    System.err.println("Error: " + result.getResponse());
}

Query Assets with Pagination

import adlabs.maestro.client.backend.api.asset.model.PaginatedAsset;
import adlabs.maestro.client.backend.factory.options.*;

// Query assets with pagination
Options options = Options.builder()
    .option(Count.of(100))
    .option(Order.desc())
    .build();

Result<PaginatedAsset> assets = maestroService.getAssetService()
    .getAssets(options);

if (assets.isSuccessful()) {
    PaginatedAsset paginatedAssets = assets.getValue();
    paginatedAssets.getData().forEach(asset -> {
        System.out.println("Asset: " + asset.getAssetName());
        System.out.println("Policy: " + asset.getPolicyId());
    });
    
    // Handle pagination
    String nextCursor = paginatedAssets.getNextCursor();
    if (nextCursor != null) {
        // Fetch next page
        Options nextPageOptions = Options.builder()
            .option(Count.of(100))
            .option(Cursor.of(nextCursor))
            .build();
    }
}

Submit Transaction

import adlabs.maestro.client.backend.api.transaction.model.SubmitRequest;
import adlabs.maestro.client.backend.api.transaction.model.SubmitResponse;

// Submit a transaction
String txCbor = "84a40081..."; // Your transaction CBOR
SubmitRequest submitRequest = new SubmitRequest();
submitRequest.setCbor(txCbor);

Result<SubmitResponse> submitResult = maestroService.getTransactionService()
    .submitTransaction(submitRequest);

if (submitResult.isSuccessful()) {
    String txHash = submitResult.getValue().getTxHash();
    System.out.println("Transaction submitted: " + txHash);
}

Advanced Query Example

Complex Filtering with Options

import adlabs.maestro.client.backend.factory.options.filters.*;

// Build complex query with filters
Options complexOptions = Options.builder()
    .option(Count.of(50))
    .option(Order.asc())
    .option(new AssetNameFilter("MyNFT"))
    .option(new PolicyIdFilter("f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a"))
    .build();

// Execute filtered query
Result<PaginatedAsset> filteredAssets = maestroService.getAssetService()
    .getAssets(complexOptions);

Environment Variables

The library supports several environment variables for configuration:

Variable	Description	Default
MAESTRO_API_KEY	Your Maestro API key	Required
MAESTRO_READ_TIMEOUT_SEC	Read timeout in seconds	300
MAESTRO_CONNECT_TIMEOUT_SEC	Connection timeout in seconds	300
MAESTRO_RETRIES_COUNT	Number of retries for failed requests	5
MAESTRO_RETRY_SLEEP_TIME_SEC	Sleep time between retries	60
MAESTRO_GZIP_COMPRESSION	Enable GZIP compression	true
MAESTRO_JAVA_LIB_LOGGING	Enable HTTP logging	false

Build Instructions

Prerequisites

• Java 11 or higher
• Maven 3.6 or higher

Building from Source

# Clone the repository
git clone https://github.com/Gero-Labs/maestro-java-client.git
cd maestro-java-client

# Build the project
mvn clean install

# Run tests
mvn test

# Generate Javadoc
mvn javadoc:javadoc

Used By

The following projects use Maestro Java Client:

• Your project here! Submit a PR to add your project.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📚 Documentation
• 💬 Discord Community
• 🐛 Issue Tracker
• 📧 Contact Support

---

Made with ❤️ by A.D. Labs