Skip to main content

CardanoDevKit API

The main entry point for Cardano DevKit.

createDevKit()​

Factory function to create a DevKit instance.

import { createDevKit } from 'cardano-devkit';

const devKit = createDevKit(config);

Parameters​

interface DevKitConfig {
  // Network to connect to
  network?: NetworkType;  // Default: 'Preprod'

  // Provider configuration
  provider?: ProviderConfig;

  // Enable debug logging
  debug?: boolean;  // Default: false

  // Local devnet specific config
  localDevnetConfig?: LocalDevnetConfig;
}

type NetworkType = 'Mainnet' | 'Preprod' | 'Preview' | 'LocalDevnet';

interface ProviderConfig {
  type: 'blockfrost' | 'koios' | 'maestro' | 'custom';
  apiKey?: string;
  baseUrl?: string;
}

interface LocalDevnetConfig {
  blockTimeMs?: number;      // Default: 1000
  slotLength?: number;       // Default: 1.0
  enableWebSocket?: boolean; // Default: false
  enableMultiNode?: boolean; // Default: false
  nodeCount?: number;        // Default: 1
}

Returns​

CardanoDevKit instance

Example​

// Basic usage
const devKit = createDevKit({
  network: 'Preprod'
});

// With Blockfrost
const devKit = createDevKit({
  network: 'Preprod',
  provider: {
    type: 'blockfrost',
    apiKey: 'your-api-key'
  }
});

// Local devnet with fast blocks
const devKit = createDevKit({
  network: 'LocalDevnet',
  localDevnetConfig: {
    blockTimeMs: 200
  },
  debug: true
});

CardanoDevKit Class​

init()​

Initialize the DevKit and connect to the network.

const lucid = await devKit.init();

Returns: Promise<Lucid> - Lucid Evolution instance

getLucid()​

Get the current Lucid instance.

const lucid = await devKit.getLucid();

Returns: Promise<Lucid>

Throws: Error if not initialized

getCurrentNetwork()​

Get the currently connected network.

const network = devKit.getCurrentNetwork();
// 'LocalDevnet' | 'Preview' | 'Preprod' | 'Mainnet'

Returns: NetworkType

switchNetwork()​

Switch to a different network.

await devKit.switchNetwork(network, options);

Parameters:

  • network: NetworkType - Target network
  • options?: SwitchOptions - Switch options
interface SwitchOptions {
  confirmMainnet?: boolean;  // Required for mainnet
  provider?: ProviderConfig; // Override provider
}

Example:

// Switch to testnet
await devKit.switchNetwork('Preprod');

// Switch to mainnet (requires confirmation)
await devKit.switchNetwork('Mainnet', { confirmMainnet: true });

useLocalDevnet()​

Switch to local devnet.

await devKit.useLocalDevnet(port?: number);

Parameters:

  • port?: number - API port (default: 10080)

usePreprod()​

Switch to Preprod testnet.

await devKit.usePreprod();

usePreview()​

Switch to Preview testnet.

await devKit.usePreview();

useMainnet()​

Switch to Mainnet.

await devKit.useMainnet(options: MainnetOptions);

Parameters:

interface MainnetOptions {
  confirmMainnet: true;  // Must be true
  checkWalletBalance?: boolean;
  requireReadOnlyFirst?: boolean;
}

Throws: Error if confirmMainnet is not true

getEnvironment()​

Get the current environment type.

const env = devKit.getEnvironment();
// 'development' | 'testnet' | 'production'

Returns: DevEnvironment

NetworkEnvironment
LocalDevnetdevelopment
Previewtestnet
Preprodtestnet
Mainnetproduction

isLocalDevnet()​

Check if connected to local devnet.

if (devKit.isLocalDevnet()) {
  // Local devnet features available
}

Returns: boolean

isTestnet()​

Check if connected to a testnet.

if (devKit.isTestnet()) {
  // Preview or Preprod
}

Returns: boolean

isSafeForTesting()​

Check if current network is safe for testing (not mainnet).

if (devKit.isSafeForTesting()) {
  // OK to run tests
}

Returns: boolean

healthCheck()​

Run a health check on the current connection.

const health = await devKit.healthCheck();

console.log('Healthy:', health.healthy);
console.log('Network:', health.network);
console.log('Provider:', health.provider);
console.log('Latency:', health.latencyMs, 'ms');

Returns:

interface HealthCheckResult {
  healthy: boolean;
  network: NetworkType;
  provider: string;
  tipSlot?: number;
  tipTime?: Date;
  latencyMs: number;
  error?: string;
}

Example:

const health = await devKit.healthCheck();

if (!health.healthy) {
  console.error('Connection issue:', health.error);
  // Try reconnecting or switch provider
}

getStatus()​

Get detailed status of the DevKit instance.

const status = devKit.getStatus();

console.log('Network:', status.network);
console.log('Initialized:', status.initialized);
console.log('Environment:', status.environment);
console.log('Provider:', status.providerType);

Returns:

interface DevKitStatus {
  network: NetworkType;
  initialized: boolean;
  environment: DevEnvironment;
  providerType: string;
  providerUrl?: string;
  walletConnected: boolean;
  walletAddress?: string;
  debug: boolean;
}

Example:

const status = devKit.getStatus();

if (!status.initialized) {
  await devKit.init();
}

if (!status.walletConnected) {
  console.warn('No wallet connected');
}

Type Definitions​

NetworkType​

type NetworkType = 'Mainnet' | 'Preprod' | 'Preview' | 'LocalDevnet';

DevEnvironment​

type DevEnvironment = 'development' | 'testnet' | 'production';

DevKitConfig​

interface DevKitConfig {
  network?: NetworkType;
  provider?: ProviderConfig;
  debug?: boolean;
  localDevnetConfig?: LocalDevnetConfig;
}

ProviderConfig​

interface ProviderConfig {
  type: 'blockfrost' | 'koios' | 'maestro' | 'custom';
  apiKey?: string;
  baseUrl?: string;
}

LocalDevnetConfig​

interface LocalDevnetConfig {
  blockTimeMs?: number;
  slotLength?: number;
  enableWebSocket?: boolean;
  enableMultiNode?: boolean;
  nodeCount?: number;
}

MainnetSwitchOptions​

interface MainnetSwitchOptions {
  confirmMainnet: true;
  checkWalletBalance?: boolean;
  requireReadOnlyFirst?: boolean;
}