Backend Services API

The Backend Services API provides integration with various Cardano backend services through a unified interface.

Key Features

• Unified Interface: Single API for multiple backend providers
• Provider Flexibility: Switch between different backend services easily
• Service Coverage: Access to blockchain data and transaction services

Core Classes

BackendService Interface

The main interface for all backend service implementations, providing access to various blockchain services.

Provider Implementations

• BFBackendService - Blockfrost integration
• KoiosBackendService - Koios REST API integration
• OgmiosBackendService - Ogmios JSON-over-HTTP for protocol params and transactions
• KupmiosBackendService - Ogmios (protocol params + tx) combined with Kupo (UTxOs) for full transaction building

Service Interfaces

• TransactionService - Transaction submission and querying
• UtxoService - UTXO management and queries
• AddressService - Address information and history
• AssetService - Native token and NFT data
• BlockService - Block information and navigation
• EpochService - Epoch information and protocol parameters

Supported Backend Services

Provider	Module	Features	Status
Blockfrost	cardano-client-backend-blockfrost	Chain data and transaction services (governance endpoints not yet available). Also compatible with Yaci Store	Stable
Koios	cardano-client-backend-koios	REST API, community-driven	Stable
Ogmios	cardano-client-backend-ogmios	Protocol parameters and transaction submission over HTTP (no UTxO API)	Stable

Usage Examples

Blockfrost Integration

Initialize Blockfrost backend service with API key:

// Initialize Blockfrost service
BackendService backendService = new BFBackendService(
    Constants.BLOCKFROST_PREPROD_URL,
    "your-project-id"
);

// Access different services
TransactionService transactionService = backendService.getTransactionService();
UtxoService utxoService = backendService.getUtxoService();
AddressService addressService = backendService.getAddressService();
AssetService assetService = backendService.getAssetService();

// Use with QuickTx
QuickTxBuilder quickTxBuilder = new QuickTxBuilder(backendService);

Koios Integration

Initialize Koios backend service for community-driven API:

// Initialize Koios service
BackendService backendService = new KoiosBackendService(Constants.KOIOS_MAINNET_URL);

// Access services
TransactionService transactionService = backendService.getTransactionService();
UtxoService utxoService = backendService.getUtxoService();
AddressService addressService = backendService.getAddressService();

// Query address information
Result<AddressContent> addressInfo = addressService.getAddressInfo("addr1...");
System.out.println("Address balance: " + addressInfo.getValue().getAmount());

Ogmios Integration

Initialize Ogmios backend service:

// Initialize Ogmios service (HTTP)
BackendService backendService = new OgmiosBackendService(
    "http://localhost:1337"
);

// Access services
TransactionService transactionService = backendService.getTransactionService();

// Submit transaction
Result<String> result = transactionService.submitTransaction(transactionCbor);
if (result.isSuccessful()) {
    System.out.println("Transaction submitted: " + result.getValue());
}

Note: Ogmios backend implements protocol parameters and transaction services. For UTXO queries, use Kupo with KupmiosBackendService (see below).

Kupmios Integration (Ogmios + Kupo)

For complete transaction building capabilities, use KupmiosBackendService which combines Ogmios and Kupo:

// Initialize Kupmios service (Ogmios + Kupo)
BackendService backendService = new KupmiosBackendService(
    "http://localhost:1337",  // Ogmios URL
    "http://localhost:1442"   // Kupo URL
);

// Only these services are available; the others throw UnsupportedOperationException:
// - Kupo provides: UtxoService
// - Ogmios provides: TransactionService, ProtocolParams
TransactionService transactionService = backendService.getTransactionService();
UtxoService utxoService = backendService.getUtxoService();
EpochService epochService = backendService.getEpochService();

For more details about Ogmios/Kupo integration, see the Ogmios backend README.

Yaci DevKit / Yaci Store (Local Development)

Yaci Store is a Cardano blockchain indexer that provides Blockfrost-compatible APIs. Since BFBackendService communicates using the Blockfrost API protocol, it works seamlessly with any Yaci Store instance — no code changes required.

Yaci DevKit bundles Yaci Store with a local Cardano devnet, giving you a complete local development environment. This is ideal for:

• Rapid iteration — no waiting for testnet confirmations
• Offline development — no internet or API keys required
• Deterministic testing — full control over the local chain

To connect to a Yaci DevKit instance running locally:

// Connect to Yaci DevKit's built-in Yaci Store (Blockfrost-compatible)
BackendService backendService = new BFBackendService(
    "http://localhost:8080/api/v1/",
    "dummy-key"
);

// Use exactly like any other BackendService
QuickTxBuilder quickTxBuilder = new QuickTxBuilder(backendService);

To connect to a hosted Yaci Store instance:

BackendService backendService = new BFBackendService(
    "https://your-yaci-store-host/api/v1/",
    "dummy-key"
);

To install and start it, see Get started with Yaci DevKit and Yaci Store documentation.

Nexus Integration

Available from 0.8.0-pre7, through the cardano-client-backend-nexus module. See the module README for setup and the Nexus SDK’s Network class.

BackendService backendService =
        new NexusBackendService("https://nexus.gerowallet.io", "<NEXUS_API_KEY>", Network.MAINNET);

Advanced Usage

Provider Switching

Each provider is instantiated directly — pick the one that fits your infrastructure:

// Blockfrost
BackendService bfService = new BFBackendService(
    Constants.BLOCKFROST_MAINNET_URL, "your-api-key");

// Koios
BackendService koiosService = new KoiosBackendService(
    com.bloxbean.cardano.client.backend.koios.Constants.KOIOS_MAINNET_URL);

// Kupmios (Ogmios + Kupo)
BackendService kupmiosService = new KupmiosBackendService(
    "http://localhost:1337", "http://localhost:1442");

Service Usage Examples

Query blockchain data using backend services:

// Get UTXO information
Result<List<Utxo>> utxos = utxoService.getUtxos("addr1...", 50, 1);
System.out.println("Found " + utxos.getValue().size() + " UTXOs");

// Get transaction details
Result<TransactionContent> transaction = transactionService.getTransaction("tx_hash...");
System.out.println("Transaction fee: " + transaction.getValue().getFees());

// Get address balance
AddressContent addressInfo = addressService.getAddressInfo("addr1...").getValue();
System.out.println("Address balance: " + addressInfo.getAmount());

Available Services

Service	Purpose	Key Methods
TransactionService	Transaction operations	submitTransaction(), getTransaction()
UtxoService	UTXO management	getUtxos(), getTxOutput()
AddressService	Address information	getAddressInfo(), getTransactions()
AssetService	Asset and token data	getAsset(), getAssetAddresses()
BlockService	Block information	getLatestBlock(), getBlockByHash()
EpochService	Epochs and protocol parameters	getLatestEpoch(), getProtocolParameters()
MetadataService	Transaction metadata	getJSONMetadataByTxnHash(), getCBORMetadataByTxnHash()
FeeCalculationService	Fee estimation	calculateFee()

The Backend Services API provides a flexible and robust foundation for Cardano blockchain integration across multiple provider ecosystems.