Skip to main content

Getting Started with Kuber-Hydra

Use this page as your launchpad for real Hydra development with Kuber. You will find setup paths, API references, and practical end-to-end examples you can run immediately.

What Kuber-Hydra gives you​

Kuber-Hydra provides a developer-friendly relay API around Hydra nodes so you can:

  • Build and submit in-head transactions with a familiar TxBuilder flow.
  • Query head state, UTxOs, and protocol parameters from one place.
  • Drive full head lifecycle operations (initialize, commit, close, fanout) without wiring low-level Hydra protocol code yourself.

In short: you write app transaction logic, and Kuber-Hydra handles most of the operational integration work.

What you will run​

  • A Cardano node (local devnet or testnet/mainnet)
  • 3 Hydra nodes for Alice, Bob, and Carol
  • 3 Kuber-Hydra relay servers for Alice, Bob, and Carol

Before running examples, make sure you have:

  • Node.js 18+
  • A package manager (pnpm, yarn, or npm)
  • Docker Desktop (required for local devnet flow)
  • Wallet/signing key files for participants
  • Enough funds for commit/collateral scenarios

If you are just starting, use local devnet first. It is faster, deterministic, and easier to debug.

Choose your setup path​

Quick start: Local devnet​

Best for fast iteration and repeatable testing. You can run full head lifecycle and transaction scenarios without waiting for public-network confirmations.

🌐 Real network: Testnet/Mainnet​

Best for realistic integration conditions. Use this path when validating wallet behavior, infrastructure setup, and production-like transaction flow.

First run checklist using Quick Start​

See more for API details - Kuber-Hydra API reference

  1. Start local cluster and verify relays are reachable.
  2. Query /query/head from Alice relay to see current state.
  3. Initialize head.
  4. Commit at least one UTxO per participant.
  5. Wait for Open.
  6. Submit one simple transfer transaction. (See - Submitting Hydra transactions )
  7. Close and fanout.
  8. Verify final L1 balances.

See more concrete examples below:

Practical examples​

Core API references​

Common pitfalls​

  • Head not Open when submitting tx: wait for state transition and retry.
  • Commit fails due to low balance/collateral: fund wallet and select larger UTxO.
  • High-fanout outputs fail: chunk outputs into multiple transactions.
  • Inconsistent local runs: reset devnet and rerun from a known state.

Suggested route by use-case​

  • Wallet integration focus: wallets -> commit -> submit tx.
  • Token lifecycle focus: mint -> burn -> verify balances.
  • Contract flow focus: pay-to-script -> follow-up spend flow.
  • Throughput focus: 100+ recipient output batching.
  1. Start with Local devnet.
  2. Run Working with wallets and Submitting Hydra transactions.
  3. Run practical advanced examples: mint, burn, pay-to-script, and high-fanout payments.
  4. Finish with the Full end-to-end example.