Hydra SDKHydra SDKDocumentation
Getting Started

Quick Start

Build your first Cardano wallet application with Hydra SDK

This guide will walk you through creating your first Cardano wallet application using Hydra SDK. In just a few minutes, you'll have a working wallet that can create accounts, build transactions, and connect to Hydra Layer 2.

Step 1: Installation

Install the essential packages:

npm install @hydra-sdk/core @hydra-sdk/bridge @hydra-sdk/transaction @hydra-sdk/cardano-wasm

Step 2: Create Your First Wallet

Create a new wallet instance with the core package:

import { AppWallet, NETWORK_ID } from '@hydra-sdk/core'

// Generate a new mnemonic phrase
const mnemonic = AppWallet.brew()
console.log('Generated mnemonic:', mnemonic.join(' '))

// Create wallet instance
const wallet = new AppWallet({
    networkId: NETWORK_ID.PREPROD, // Use PREPROD for testing
    key: {
        type: 'mnemonic',
        words: mnemonic
    }
})

// Get the first account
const account = wallet.getAccount(0, 0)
console.log('Wallet Address:', account.baseAddressBech32)

Restore Existing Wallet

To restore a wallet from an existing mnemonic:

const existingMnemonic = 'your existing mnemonic phrase here'.split(' ')

const restoredWallet = new AppWallet({
    networkId: NETWORK_ID.PREPROD,
    key: {
        type: 'mnemonic',
        words: existingMnemonic
    }
})

Step 3: Query UTxOs and Build Transactions

First, query UTxOs from your wallet address, then use the transaction builder:

import { TxBuilder } from '@hydra-sdk/transaction'
import { ProviderUtils } from '@hydra-sdk/core'

// Initialize a provider (Blockfrost or Ogmios)
const blockfrostProvider = new ProviderUtils.BlockfrostProvider({
    apiKey: 'your-blockfrost-api-key',
    network: 'preprod'
})

// Set provider for wallet
const wallet = new AppWallet({
    networkId: NETWORK_ID.PREPROD,
    key: {
        type: 'mnemonic',
        words: mnemonic
    },
    fetcher: blockfrostProvider.fetcher,
    submitter: blockfrostProvider.submitter
})

// Get wallet address
const account = wallet.getAccount(0, 0)
const walletAddress = account.baseAddressBech32

// Query UTxOs from wallet
const utxos = await wallet.queryUTxOs(walletAddress)
console.log('Available UTxOs:', utxos.length)

// Build a simple ADA transfer
const recipientAddress = 'addr_test1...' // Recipient's address
const amountToSend = '1000000' // 1 ADA in lovelace

try {
    // Initialize transaction builder
    const txBuilder = new TxBuilder()

    const tx = await txBuilder
        .setInputs(utxos) // Use queried UTxOs as inputs
        .addOutput({
            address: recipientAddress,
            amount: [{ unit: 'lovelace', quantity: amountToSend }]
        })
        .changeAddress(walletAddress) // Change returns to sender
        .complete()

    console.log('Transaction built:', tx.to_hex())

    // Sign the transaction
    const signedTx = await wallet.signTx(tx.to_hex())
    console.log('Transaction signed')

    // Submit transaction
    const txHash = await wallet.submitTx(signedTx)
    console.log('Transaction submitted! Hash:', txHash)
} catch (error) {
    console.error('Transaction failed:', error)
}

Advanced Transaction Example

Build a transaction with multiple outputs and native tokens:

import { TxBuilder } from '@hydra-sdk/transaction'

const txBuilder = new TxBuilder()

// Query UTxOs
const utxos = await wallet.queryUTxOs(walletAddress)

const tx = await txBuilder
    .setInputs(utxos)
    // Send ADA to first recipient
    .addOutput({
        address: 'addr_test1qr...',
        amount: [{ unit: 'lovelace', quantity: '2000000' }]
    })
    // Send ADA + Native Token to second recipient
    .addOutput({
        address: 'addr_test1qs...',
        amount: [
            { unit: 'lovelace', quantity: '1500000' },
            { unit: 'policyId.assetName', quantity: '100' }
        ]
    })
    .changeAddress(walletAddress)
    .complete()

const signedTx = await wallet.signTx(tx.to_hex())
const txHash = await wallet.submitTx(signedTx)
console.log('Transaction hash:', txHash)

Step 4: Connect to Hydra Layer 2

Create a Hydra Bridge to connect to Hydra Heads for fast Layer 2 transactions:

import { HydraBridge, HydraPayload } from '@hydra-sdk/bridge'

// Create Hydra Bridge instance
const bridge = new HydraBridge({
    url: 'ws://localhost:4001', // Your Hydra Node WebSocket URL
    autoReconnect: true,        // Auto-reconnect on drop
    reconnectInterval: 3000     // Retry every 3s
})

// Listen for connection events
bridge.events.on('onConnected', () => {
    console.log('Connected to Hydra Head!')
})

bridge.events.on('onMessage', (payload: HydraPayload) => {
    if (payload.tag === 'HeadIsOpen') {
        // After Greetings, snapshot cache is seeded automatically
        // Use getAddressBalance() for O(1) reads — no HTTP call
        const balance = bridge.getAddressBalance('addr_test1...')
        console.log('ADA:', balance?.get('lovelace')?.toString())
    }
})

// Connect to the Hydra Node
await bridge.connect()

Connect to Hydra Layer 2 using HexcoreConnector

Create a Hydra Bridge to connect to Hydra Heads using HexcoreConnector:

import { HydraBridge, HexcoreConnector } from '@hydra-sdk/bridge'

const hexcoreConnector = new HexcoreConnector('wss://example.hexcore.io.vn/hydra', {
    socketIoOptions: {
        auth: {
            token: 'your_auth_token'
        }
    }
})
// Create Hydra Bridge instance
const bridge = new HydraBridge({
    connector: hexcoreConnector
})

// Listen for connection events
bridge.events.on('onConnected', () => {
    console.log('Connected to Hydra Head!')
})

bridge.events.on('onMessage', (payload: HydraPayload) => {
    console.log('>>> / onMessage:', payload)
})

// Connect to the Hydra Node
await bridge.connect()

Next Steps

Now that you have a working wallet application, explore these advanced topics:

Need Help?

Installation

Learn how to install Hydra SDK packages in your project

Configuration

Configure your build tools and environment for Hydra SDK