Cardano

The @stakefish/sdk-cardano is a JavaScript/TypeScript library that provides a unified interface for staking operations on the Cardano blockchain with stake.fish validators. It allows developers to easily delegate stakes, undelegate, withdraw rewards, delegate to DRep, sign transactions, and broadcast them to the network.

Installation
Type Imports
API Reference
Examples
Notes

Installation

To use this SDK in your project, install it via npm or yarn:

npm install @stakefish/sdk-cardano

yarn add @stakefish/sdk-cardano

Type Imports

import { Cardano } from '@stakefish/sdk-cardano';
import type {
  CardanoConfig,
  CardanoPrepareDelegate,
  CardanoPrepareUndelegate,
  CardanoPrepareWithdraw,
  CardanoPrepareDrepDelegate,
  CardanoDeriveKeys,
  CardanoSign,
  CardanoBroadcast,
  CardanoUnsignedTransaction,
  CardanoSignedTransaction,
  CardanoTransactionBroadcastResult,
  CardanoKeys,
} from '@stakefish/sdk-cardano';

API Reference

Constructor

import type { CardanoConfig } from '@stakefish/sdk-cardano';

new Cardano({ blockfrostProjectId: 'your-project-id', memo: 'Stake with stake.fish' }: CardanoConfig)

Creates a new Cardano SDK instance.

Parameters:

blockfrostProjectId (required): Your Blockfrost project ID for API access
blockfrostUrl (optional): Blockfrost API endpoint URL (default: mainnet)
memo (required): Memo to include in transactions. This should be a unique string approved by stake.fish for your account.

Delegation

import type { CardanoPrepareDelegate, CardanoUnsignedTransaction } from '@stakefish/sdk-cardano';

delegate({ delegatorAddress: 'addr1...' }: CardanoPrepareDelegate): Promise<CardanoUnsignedTransaction>

Creates an unsigned transaction for delegating to the stake.fish validator pool. The transaction automatically handles the stake registration if needed and delegates the entire stake account to the validator.

Parameters:

delegatorAddress: The Cardano address of the delegator (e.g., 'addr1...')

Undelegation

import type { CardanoPrepareUndelegate, CardanoUnsignedTransaction } from '@stakefish/sdk-cardano';

undelegate({ delegatorAddress: 'addr1...' }: CardanoPrepareUndelegate): Promise<CardanoUnsignedTransaction>

Creates an unsigned transaction for undelegating from the stake.fish validator pool. This deregisters the stake key, effectively undelegating all staked ADA.

Parameters:

delegatorAddress: The Cardano address of the delegator

Withdraw Rewards

import type { CardanoPrepareWithdraw, CardanoUnsignedTransaction } from '@stakefish/sdk-cardano';

withdraw({ delegatorAddress: 'addr1...' }: CardanoPrepareWithdraw): Promise<CardanoUnsignedTransaction>

Creates an unsigned transaction for withdrawing accumulated staking rewards from the stake.fish validator.

Parameters:

delegatorAddress: The Cardano address of the delegator

Set DRep

import type { CardanoPrepareDrepDelegate, CardanoUnsignedTransaction } from '@stakefish/sdk-cardano';

setDrep({ delegatorAddress: 'addr1...' }: CardanoPrepareDrepDelegate): Promise<CardanoUnsignedTransaction>

Creates an unsigned transaction for setting DRep to always-abstain.

Parameters:

delegatorAddress: The Cardano address of the delegator

Key Derivation

import type { CardanoDeriveKeys, CardanoKeys } from '@stakefish/sdk-cardano';

deriveKeysFromMnemonic({ mnemonic: 'word1 word2 ...', accountIndex: 0 }: CardanoDeriveKeys): CardanoKeys

Derives Cardano cryptographic keys from a BIP-39 mnemonic phrase following the CIP-1852 standard. This is a helper method to obtain the necessary keys for signing transactions.

Parameters:

mnemonic: A valid BIP-39 mnemonic phrase (12, 15, 18, 21, or 24 words)
accountIndex: The account index to derive (typically 0 for the first account)

Returns: CardanoKeys object containing:

stakePrivateKey: Private key for stake operations
paymentPrivateKey: Private key for payment operations
stakePublicKey: Public key for stake operations
paymentPublicKey: Public key for payment operations

Signing

import type { CardanoSign, CardanoSignedTransaction } from '@stakefish/sdk-cardano';

sign({ keys, unsignedTx }: CardanoSign): Promise<CardanoSignedTransaction>

Signs the unsigned transaction using the provided Cardano keys. This operation works completely offline and does not require network connectivity. Both stake and payment keys are used to sign the transaction.

Parameters:

keys: CardanoKeys object containing stake and payment private/public key pairs
unsignedTx: The unsigned transaction object from delegate(), undelegate(), or withdraw()

Broadcasting

import type { CardanoBroadcast, CardanoTransactionBroadcastResult } from '@stakefish/sdk-cardano';

broadcast({ signedTransaction, checkInclusion, timeoutMs, pollIntervalMs }: CardanoBroadcast): Promise<CardanoTransactionBroadcastResult>

Broadcasts the signed transaction to the Cardano network and optionally waits for inclusion confirmation.

Parameters:

signedTransaction: The signed transaction object from sign()
checkInclusion (optional): Whether to wait for transaction inclusion (default: true)
timeoutMs (optional): Maximum time to wait for inclusion in milliseconds (default: 60000)
pollIntervalMs (optional): Interval between inclusion checks in milliseconds (default: 2000)

Returns: CardanoTransactionBroadcastResult object containing:

txId: The transaction hash
blockHash: The block hash if included (optional)
blockHeight: The block height if included (optional)

Examples

Full delegation example

import { Cardano } from '@stakefish/sdk-cardano';
import type {
  CardanoKeys,
  CardanoUnsignedTransaction,
  CardanoSignedTransaction,
  CardanoTransactionBroadcastResult,
} from '@stakefish/sdk-cardano';
// or: const { Cardano } = require('@stakefish/sdk-cardano');

const delegatorAddress = process.env.CARDANO_ADDRESS;
const mnemonic = process.env.CARDANO_MNEMONIC;
const blockfrostProjectId = process.env.CARDANO_BLOCK_FROST_PROJECT_ID;

async function main() {
  const cardano = new Cardano({
    blockfrostProjectId,
    memo: 'Stake with stake.fish',
  });

  // Delegation
  const unsignedTx: CardanoUnsignedTransaction = await cardano.delegate({ delegatorAddress });

  // Derive keys from mnemonic
  const keys: CardanoKeys = cardano.deriveKeysFromMnemonic({ mnemonic, accountIndex: 0 });

  // Sign
  const signedTx: CardanoSignedTransaction = await cardano.sign({ keys, unsignedTx });

  // Broadcast
  const result: CardanoTransactionBroadcastResult = await cardano.broadcast({ signedTransaction: signedTx });
  console.log('Broadcast result:', JSON.stringify(result));
}

void main().catch(console.error);

Undelegation

const unsignedTx: CardanoUnsignedTransaction = await cardano.undelegate({ delegatorAddress });

Withdraw Rewards

const unsignedTx: CardanoUnsignedTransaction = await cardano.withdraw({ delegatorAddress });

Set DRep

const unsignedTx: CardanoUnsignedTransaction = await cardano.setDrep({ delegatorAddress });

Configuration

The SDK requires configuration during instantiation with Blockfrost API credentials:

const cardano = new Cardano({
  blockfrostProjectId: 'your-blockfrost-project-id',
  blockfrostUrl: 'https://cardano-mainnet.blockfrost.io/api/v0',
  memo: 'Stake with stake.fish',
});

Notes

All amounts in Cardano are specified in lovelace, the smallest unit of ADA (1 ADA = 1,000,000 lovelace)
The SDK automatically handles transaction fees and UTxO management
Cardano delegation does not require specifying amounts - the entire stake account is delegated
Private keys and mnemonics should be kept secure and never committed to version control
The SDK uses the Blockfrost API for network interactions
Key derivation follows the CIP-1852 standard for Cardano HD wallets
Both stake and payment keys are required to sign transactions

Table of Contents

Installation

Type Imports

API Reference

Constructor

Delegation

Undelegation

Withdraw Rewards

Set DRep

Key Derivation

Signing

Broadcasting

Examples

Full delegation example

Undelegation

Withdraw Rewards

Set DRep

Configuration

Notes