midnight-wallet-cli

A standalone CLI wallet for the Midnight blockchain. Manage wallets, check balances, transfer NIGHT tokens, and run a local network — all from the terminal.

Note: This repository hosts documentation and issue tracking. Source code will be open-sourced in a future release.

Install

npm install -g midnight-wallet-cli

This installs two commands: midnight (or mn for short) and midnight-wallet-mcp.

Commands

Command	Description
midnight wallet generate <name>	Create a named wallet and set it as active
midnight wallet list	List all wallets with active marker
midnight wallet use <name>	Set the active wallet
midnight wallet info [name]	Show wallet details
midnight wallet remove <name>	Remove a wallet
midnight info	Display wallet address, network, creation date
midnight balance [address]	Check unshielded NIGHT balance
midnight transfer <to> <amount>	Send NIGHT tokens to another address
midnight airdrop <amount>	Fund wallet from genesis (undeployed network only)
midnight dust register	Register NIGHT UTXOs for dust (fee token) generation
midnight dust status	Check dust registration status and balance
midnight address --seed <hex>	Derive an address from a seed
midnight genesis-address	Show the genesis wallet address
midnight inspect-cost	Display current block cost limits
midnight serve	Start DApp Connector server (WebSocket JSON-RPC)
midnight config get/set	Manage persistent config (network, wallet, endpoints)
midnight cache clear	Clear wallet state cache
midnight localnet up/stop/down/status	Manage a local Midnight network via Docker
midnight help [command]	Show usage for all or a specific command

Quick Start

Local development (undeployed)

# 1. Start local network (node, indexer, proof server)
midnight localnet up

# 2. Create a wallet and set the network
midnight wallet generate alice
midnight config set network undeployed

# 3. Fund your wallet and register dust (needed for fees)
midnight airdrop 1000
midnight dust register

# 4. Check balance and transfer
midnight balance
midnight transfer mn_addr_undeployed1... 100

Preprod / Preview (testnet)

# 1. Create a wallet and set the network
midnight wallet generate alice
midnight config set network preprod   # or: preview

# 2. Get test tokens from the faucet
#    preprod: https://faucet.preprod.midnight.network/
#    preview: https://faucet.preview.midnight.network/
#    Paste your address from: midnight wallet info alice

# 3. Register dust (needed for fees)
midnight dust register

# 4. Check balance and transfer
midnight balance
midnight transfer mn_addr_preprod1... 100

See Getting Started for a detailed walkthrough.

Supported Networks

Network	Description
undeployed	Local network via Docker (midnight localnet up)
preprod	Midnight pre-production testnet
preview	Midnight preview testnet

Wallets are network-agnostic — one seed derives addresses for all three networks. Use --network <name> on any command, or persist it with midnight config set network preview.

See Networks for configuration details.

DApp Connector

midnight serve starts a WebSocket JSON-RPC server that implements the same ConnectedAPI interface as the Lace browser wallet. Any DApp can connect to it — no browser extension needed.

# Start the connector server
midnight serve --network preview

# Or auto-approve all requests (dev only)
midnight serve --network preview --approve-all

To connect from your DApp, install the connector package:

npm install midnight-wallet-connector

import { createWalletClient } from 'midnight-wallet-connector';

const wallet = await createWalletClient({
  url: 'ws://localhost:9932',
  networkId: 'Preview',
});

const balances = await wallet.getUnshieldedBalances();

See the midnight-wallet-connector package for the full API, and midnight-starship for a working example DApp.

JSON Output for Automation

Every command supports --json for structured output:

midnight balance --json
# → {"address":"mn_addr_...","network":"undeployed","balances":{"NIGHT":"504.850000"},"utxoCount":2,"txCount":8}

midnight transfer mn_addr_... 100 --json
# → {"txHash":"00ab...","amount":100,"recipient":"mn_addr_...","network":"undeployed"}

When --json is active:

• stdout receives a single line of JSON
• stderr is fully suppressed (no spinners, no formatting)
• Errors produce: {"error":true,"code":"...","message":"...","exitCode":N}

Run midnight help --json for a full capability manifest, or midnight help --agent for a comprehensive AI agent reference.

See JSON Output Reference for all schemas and error codes.

MCP Server for AI Agents

The package includes an MCP (Model Context Protocol) server that exposes all wallet operations as typed tools. AI agents call them directly via JSON-RPC over stdio — no shell spawning or output parsing needed.

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "midnight-wallet": {
      "command": "midnight-wallet-mcp"
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "midnight-wallet": {
      "command": "midnight-wallet-mcp"
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "midnight-wallet": {
      "command": "midnight-wallet-mcp"
    }
  }
}

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "midnight-wallet": {
      "type": "stdio",
      "command": "midnight-wallet-mcp"
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "midnight-wallet": {
      "command": "midnight-wallet-mcp"
    }
  }
}

Tip: If you haven't installed globally, use "command": "npx" with "args": ["-y", "midnight-wallet-cli@latest", "--mcp"] instead.

Available MCP Tools

Once connected, your AI agent gets access to 24 tools:

Tool	Description
midnight_wallet_generate	Create a named wallet
midnight_wallet_list	List all wallets
midnight_wallet_use	Set active wallet
midnight_wallet_info	Show wallet details
midnight_wallet_remove	Remove a wallet
midnight_generate	Generate a wallet (deprecated)
midnight_info	Show wallet info (no secrets)
midnight_balance	Check NIGHT balance
midnight_address	Derive address from seed
midnight_genesis_address	Show genesis wallet address
midnight_inspect_cost	Show block cost limits
midnight_airdrop	Fund wallet from genesis
midnight_transfer	Send NIGHT tokens
midnight_dust_register	Register UTXOs for dust generation
midnight_dust_status	Check dust status
midnight_config_get	Read config value
midnight_config_set	Write config value
midnight_config_unset	Remove config value
midnight_cache_clear	Clear wallet state cache
midnight_localnet_up	Start local network
midnight_localnet_stop	Stop local network
midnight_localnet_down	Remove local network
midnight_localnet_status	Show service status
midnight_localnet_clean	Remove conflicting containers

See MCP Server Guide for detailed setup and example workflows.

Documentation

• Getting Started — Full walkthrough from install to first transfer
• Command Reference — Every command with flags, examples, and JSON schemas
• JSON Output — Structured output format, error codes, shell scripting
• MCP Server — AI agent integration guide
• Networks — Network configuration and detection
• Changelog — Version history

Requirements

• Node.js >= 20
• Docker (for midnight localnet commands)
• A running proof server on localhost:6300 (for transactions — required on all networks)

Issues & Feedback

Found a bug or have a feature request? Open an issue.

License

Apache-2.0