Guides

Integrate from Cardano-CLI

Learn how to use Cardano-CLI generated keys with Hydra SDK using CardanoCliWallet.

Learn how to use keys generated from Cardano-CLI with Hydra SDK. The CardanoCliWallet class allows you to use existing CLI keys in your Node.js applications for programmatic transaction signing and blockchain interactions.

Reference: Cardano-CLI Documentation

Generate Keys with Cardano-CLI

Generate a payment key pair using Cardano-CLI:

cardano-cli address key-gen \
  --verification-key-file payment.vkey \
  --signing-key-file payment.skey

This will create two files:

payment.vkey (Verification Key):

{
    "type": "PaymentVerificationKeyShelley_ed25519",
    "description": "Payment Verification Key",
    "cborHex": "5820832ba166c8ba8afda5b9d85dfe13dd8fffd460da79a2c3cf34e107216637985b"
}

payment.skey (Signing Key):

{
    "type": "PaymentSigningKeyShelley_ed25519",
    "description": "Payment Signing Key",
    "cborHex": "5820bd09ad4f98cd103e059ab62d17a6a7d920b16d9f0eed3eb6b77d3ca8f61dc117"
}

⚠️ Security Warning: Never share your signing key (payment.skey) or commit it to version control.

Verify Keys (Optional)

Verify your keys by building an address:

cardano-cli address build \
  --payment-verification-key-file payment.vkey \
  --testnet-magic 1 \
  --out-file payment.addr

Output (payment.addr):

addr_test1vz5hhyn6ecl66a2ca3cwfnwu8ddnp24hakfq2k37rhk28ysk8g0wz

This is an enterprise address (payment-only, no staking key) following CIP-19.

Use with Hydra SDK

Basic Setup

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

// Extract the cborHex values from your key files
const skey = '5820bd09ad4f98cd103e059ab62d17a6a7d920b16d9f0eed3eb6b77d3ca8f61dc117';
const vkey = '5820832ba166c8ba8afda5b9d85dfe13dd8fffd460da79a2c3cf34e107216637985b';

// Initialize the wallet
const wallet = new CardanoCliWallet({ 
    skey, 
    vkey, 
    networkId: NETWORK_ID.PREPROD 
});

// Get address in Bech32 format
const address = wallet.getAddressBech32();
console.log('Wallet Address:', address);
// Output: addr_test1vz5hhyn6ecl66a2ca3cwfnwu8ddnp24hakfq2k37rhk28ysk8g0wz

Transaction Example

import { 
    CardanoCliWallet, 
    NETWORK_ID,
    ProviderUtils
} from '@hydra-sdk/core';
import { TxBuilder } from '@hydra-sdk/transaction';

// Initialize wallet with CLI keys
const wallet = new CardanoCliWallet({ 
    skey: '5820bd09ad4f98cd103e059ab62d17a6a7d920b16d9f0eed3eb6b77d3ca8f61dc117',
    vkey: '5820832ba166c8ba8afda5b9d85dfe13dd8fffd460da79a2c3cf34e107216637985b',
    networkId: NETWORK_ID.PREPROD 
});

// Setup provider
const provider = new ProviderUtils.BlockfrostProvider({
    apiKey: 'your-blockfrost-project-id',
    network: 'preprod'
});

// Build transaction
const txBuilder = new TxBuilder({
    fetcher: provider.fetcher,
    submitter: provider.submitter
});
const unsignedTx = await txBuilder
    // ...
    .complete();

// Sign transaction
const signedTxCbor = await wallet.signTx(unsignedTx.to_hex());
console.log('Signed Transaction:', signedTxCbor);

API Reference

Constructor

new CardanoCliWallet(options: CardanoCliWalletConfig)

Options:

skey (required): CBOR hex of the signing key — plain (5820...) or extended (5880...)
vkey (required): CBOR hex of the verification key — plain (5820...) or extended (5840...)
networkId (optional): NETWORK_ID.MAINNET (1) or NETWORK_ID.PREPROD (0), default is MAINNET
fetcher (optional): Custom fetcher for querying UTxOs
submitter (optional): Custom submitter for transaction submission

Extended (BIP32-Ed25519) keys

CardanoCliWallet accepts both key families that cardano-cli writes:

Envelope type	`cborHex`	Payload
`PaymentSigningKeyShelley_ed25519`	`5820...`	32-byte ed25519 key
`PaymentExtendedSigningKeyShelley_ed25519_bip32`	`5880...`	128-byte xprv (`prv \| pub \| chaincode`)
`PaymentVerificationKeyShelley_ed25519`	`5820...`	32-byte ed25519 key
`PaymentExtendedVerificationKeyShelley_ed25519_bip32`	`5840...`	64-byte xpub (`pub \| chaincode`)

Keys derived from a mnemonic are always extended, so KeysUtils.mnemonicToCliKey() returns an extended pair. Feeding that pair to CardanoCliWallet yields the same address and the same signatures as the AppWallet built from the same mnemonic:

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

const mnemonic = AppWallet.brew()

const wallet = new AppWallet({ key: { type: 'mnemonic', words: mnemonic }, networkId: NETWORK_ID.PREPROD })
const { sk, vk } = KeysUtils.mnemonicToCliKey(mnemonic, 0, 0)

const cliWallet = new CardanoCliWallet({
    skey: sk.cborHex,
    vkey: vk.cborHex,
    networkId: NETWORK_ID.PREPROD
})

cliWallet.getAddressBech32() === wallet.getAccount(0, 0).enterpriseAddressBech32 // true

An extended key cannot be narrowed to a plain 32-byte PaymentSigningKeyShelley_ed25519. The first half of a BIP32-Ed25519 key is already the ed25519 scalar, whereas a plain key is a seed that ed25519 hashes into a scalar — passing one as the other derives a different public key, and therefore a different address.

Methods

// Get address in Bech32 format
getAddressBech32(): string

// Sign a transaction
signTx(unsignedTxHex: string, partialSign?: boolean): Promise<string>

// Get network ID
getNetworkId(): number

// Submit transaction (requires submitter in constructor)
submitTx(tx: string): Promise<string>

// Query UTxOs (requires fetcher in constructor)
queryUTxOs(address: string): Promise<UTxO[]>

Properties

// Get payment signing key
paymentSKey: CardanoWASM.PrivateKey

// Get payment verification key
paymentVKey: CardanoWASM.PublicKey

Next Steps

Utilities Cookbook

Task-oriented recipes for the Hydra SDK utility namespaces — datums, redeemers, time, policies, providers, and more.

Why Hydra?

Understanding the benefits and use cases of Hydra Layer 2 scaling solution