Skip to main content

Quick Start

Get up and running with Cardano DevKit in 5 minutes.

1. Start Local Devnet​

# Start with default settings (1 second blocks)
npx cardano-devkit start

# Or with fast blocks for rapid development
npx cardano-devkit start --block-time 200

You'll see:

🚀 Starting local Cardano devnet...
   Port: 10080
   Block time: 200ms
✅ Devnet started successfully!
   API: http://localhost:10080/api/v1
   WebSocket: ws://localhost:10180/ws
   Explorer: http://localhost:10173

2. Initialize DevKit​

import { createDevKit, WalletHelper } from 'cardano-devkit';

// Connect to local devnet
const devKit = createDevKit({ network: 'LocalDevnet' });
const lucid = await devKit.init();

// Check system health
const status = await devKit.healthCheck();
console.log('System healthy:', status.healthy);

// Generate a new wallet
const seed = WalletHelper.generateSeed();
lucid.selectWallet.fromSeed(seed);

const address = await lucid.wallet().address();
console.log('Your address:', address);

Using Namespace Imports​

For cleaner, more organized code:

import { createDevKit } from 'cardano-devkit';
import { ADA, Address, Transaction, Debug } from 'cardano-devkit/namespaces';

// Enable debug mode during development
Debug.enable({ level: 'debug', timestamps: true });

const devKit = createDevKit({ network: 'LocalDevnet' });
const lucid = await devKit.init();

// Use namespaces for clarity
const amount = ADA.toLovelace(10);        // 10_000_000n
const isValid = Address.validate(addr);   // true/false
const formatted = ADA.format(5_000_000n); // "5 ₳"

3. Fund Your Wallet​

# Via CLI
npx cardano-devkit topup addr_test1qz...

# Or programmatically
import { createDevnetManager } from 'cardano-devkit';

const devnet = createDevnetManager();
const txHash = await devnet.topup(address, 1000_000_000n); // 1000 ADA
console.log('Funded!', txHash);

4. Build Your First Transaction​

import { ADA, Transaction } from 'cardano-devkit/namespaces';

// Build the transaction
const tx = await lucid
  .newTx()
  .pay.ToAddress("addr_test1...", { lovelace: ADA.toLovelace(10) })
  .complete();

// Preview before signing (optional but recommended)
const preview = await Transaction.preview(lucid, tx);
console.log('Fee:', ADA.format(preview.fee));
console.log('Outputs:', preview.outputs.length);

// Sign and submit
const signedTx = await tx.sign.withWallet().complete();
const txHash = await signedTx.submit();

console.log('Transaction submitted:', txHash);

5. Check Status​

# View chain tip
npx cardano-devkit tip

# View devnet status
npx cardano-devkit status

# Run diagnostics
npx cardano-devkit diagnose

Or programmatically:

import { diagnose, isHealthy, quickBalance } from 'cardano-devkit';

// Quick health check
if (await isHealthy(devKit)) {
  console.log('All systems operational');
}

// Quick balance check
const balance = await quickBalance(devKit);
console.log(`Balance: ${balance.ada} ADA`);

// Full diagnostics
const diag = await diagnose(devKit);
console.log('Network:', diag.network.status);
console.log('Wallet:', diag.wallet.status);

6. Debug Issues​

Enable debug mode to trace transactions:

import { enableDebug, traceTransaction, formatTrace } from 'cardano-devkit';

// Enable debug logging
enableDebug({ level: 'debug', timestamps: true });

// Trace a transaction through its lifecycle
const { txHash, trace } = await traceTransaction(lucid, async (l) => {
  const tx = await l.newTx()
    .pay.ToAddress(recipient, { lovelace: 10_000_000n })
    .complete();
  const signed = await tx.sign.withWallet().complete();
  return await signed.submit();
});

// See timing breakdown
console.log(formatTrace(trace));
// Phase: build    - 145ms
// Phase: sign     - 52ms
// Phase: submit   - 1203ms
// Total: 1400ms

Development Workflow​

Local Development (Fast Iteration)​

const devKit = createDevKit({ network: 'LocalDevnet' });
// 200ms blocks, instant feedback

Testnet Staging​

await devKit.usePreprod();
// Test on public testnet

Production Deployment​

await devKit.useMainnet({ confirmMainnet: true });
// Deploy to mainnet (requires explicit confirmation)

Project Scaffolding​

Use the interactive wizard to set up a new project:

npx cardano-devkit init --wizard

Or generate code artifacts:

# Generate a test wallet
npx cardano-devkit generate wallet --network Preprod

# Generate smart contract template
npx cardano-devkit generate contract escrow

# Generate React component
npx cardano-devkit generate component WalletButton

Next Steps​