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.

Built for two audiences: beginners starting their first Midnight project (localnet + funded wallets + contract deploy in under 5 minutes), and AI agents (Cursor, Claude Code, any MCP client) using the same primitives via a built-in MCP server.

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 + shielded NIGHT balance
`midnight transfer <to> <amount>`	Send NIGHT tokens (`--shielded` for shielded)
`midnight airdrop <amount>`	Fund a wallet or raw address from genesis (`--shielded` for shielded, undeployed 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 contract inspect`	Show circuits, witnesses, and types for a compiled contract
`midnight contract deploy`	Deploy a contract to the network
`midnight contract call`	Call a circuit on a deployed contract
`midnight contract state`	Read ledger state of a deployed contract
`midnight dev`	Contract dev loop — watcher auto-compiles on save; `[t]` runs tests, `[d]` deploys
`midnight test create/run/list/results`	Generate and run E2E tests for Midnight dApps
`midnight config get/set/unset`	Manage persistent config (network, wallet, endpoints)
`midnight cache clear`	Clear wallet state cache
`midnight localnet up/stop/down/status/logs/clean`	Manage a local Midnight network via Docker
`midnight help [command]`	Show usage for all or a specific command
`midnight manual`	Full reference manual (every command, every flag)

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

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.

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_...","shieldedAddress":"mn_shield-addr_...","network":"undeployed","unshielded":{"NIGHT":"1000.000000","utxoCount":1},"shielded":{"NIGHT":"10.000000","availableCoins":1,"pendingCoins":0}}

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

When --json is active:

stdout receives a single line of JSON (the data)
stderr keeps showing chrome (spinners, headers, progress) — pipe through 2>/dev/null if you need it gone
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.

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 30 tools:

Tool	Description
`midnight_wallet_generate`	Create a named wallet
`midnight_wallet_list`	List all wallets (slim by default — see "Agent-slim responses" below)
`midnight_wallet_use`	Set active wallet
`midnight_wallet_info`	Show wallet details (slim by default)
`midnight_wallet_remove`	Remove a wallet
`midnight_info`	Show wallet info (no secrets)
`midnight_balance`	Check NIGHT balance (slim by default)
`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 (returns a pending token; confirm with `midnight_confirm_operation`)
`midnight_confirm_operation`	Execute a previously-returned pending operation (transfer/contract confirmation flow)
`midnight_dust_register`	Register UTXOs for dust generation
`midnight_dust_status`	Check dust status (slim by default)
`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
`midnight_localnet_logs`	Snapshot of recent logs from each service
`midnight_contract_inspect`	Read circuits, witnesses, ledger shape from a compiled contract; lists `siblings` for multi-contract projects
`midnight_contract_state`	Query a deployed contract's ledger state
`midnight_contract_deploy`	Deploy a compiled contract (returns pending token; confirm with `midnight_confirm_operation`)
`midnight_contract_call`	Call a circuit on a deployed contract (returns pending token; auto-coerces numbers/`"123n"` strings to BigInt and `[0–255]` arrays to Uint8Array)
`midnight_test_create`	Generate a CLI or browser test scaffold from the compiled contract

Every response carries _serverVersion so a stale MCP server (CLI on disk says X, responses still say Y) is detectable — see "Stale MCP server" in docs/SKILL.md.

Agent-slim responses

wallet_list, wallet_info, balance, and dust_status return a slim JSON shape by default — agents pay roughly half the tokens of the legacy --json shape. Pass { full: true } to get the same shape mn <cmd> --json emits (per-network address maps, sync internals, etc.):

midnight_wallet_list()              // slim: { name, active, network, address, shieldedAddress } per wallet
midnight_wallet_list({ full: true }) // full: per-network addresses + shieldedAddresses maps (legacy shape)

The CLI human paths (mn wallet list --json, etc.) are unchanged.

Skill resources

Two markdown resources teach agents how to use the CLI:

midnight-wallet://skill/core — intent routing + safety rules. ~890 tokens. Fetch on session start.
midnight-wallet://skill/full — canonical flows, error recovery, concept primers. ~2.4k tokens. Fetch on demand (errors, multi-step flows).

The legacy midnight-wallet://skill URI still works as an alias for /full.

Structured error codes

Every tool error returns { error: true, code: <CODE>, message: <human prose> }. Agents should index on the stable code (INSUFFICIENT_BALANCE, DUST_REQUIRED, INVALID_DUST_PROOF, STALE_CACHE, PROOF_FAILURE, SYNC_TIMEOUT, NETWORK_ERROR, WALLET_NOT_FOUND, INVALID_ARGS, TX_REJECTED, STALE_UTXO, PROOF_TIMEOUT, CANCELLED, UNKNOWN) — full taxonomy + recovery recipes are in docs/SKILL.md.

Issues & Feedback

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

Requirements

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

Development

Working on the CLI itself? Clone, install, build, test:

git clone https://github.com/nel349/midnight-wallet-cli.git
cd midnight-wallet-cli
npm install
npm run build       # bun build → dist/wallet.js + dist/mcp-server.js
npm test            # vitest run
npm run typecheck   # tsc --noEmit

Run the CLI directly from source without rebuilding:

npx tsx src/wallet.ts <command>     # or: npm run wallet -- <command>
npx tsx src/mcp-server.ts           # or: npm run mcp

Contributing

Contributions welcome. See CONTRIBUTING.md for the workflow, coding standards, and testing requirements.

Quick checklist before opening a PR:

npm run typecheck clean
npm test green
New behavior covered by a test in src/__tests__/
Commit messages follow the repo style (feat(scope): …, fix(scope): …, etc.)

License

Apache-2.0. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 235 Commits
.github/workflows		.github/workflows
demo/images		demo/images
docs		docs
hub		hub
packages/connector		packages/connector
scripts		scripts
src		src
tasks/archive		tasks/archive
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

midnight-wallet-cli

Install

Commands

Quick Start

Local development (undeployed)

Preprod / Preview (testnet)

Supported Networks

DApp Connector

JSON Output for Automation

MCP Server for AI Agents

Claude Code

Claude Desktop

Cursor

VS Code (GitHub Copilot)

Windsurf

Available MCP Tools

Agent-slim responses

Skill resources

Structured error codes

Issues & Feedback

Requirements

Development

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

midnight-wallet-cli

Install

Commands

Quick Start

Local development (undeployed)

Preprod / Preview (testnet)

Supported Networks

DApp Connector

JSON Output for Automation

MCP Server for AI Agents

Claude Code

Claude Desktop

Cursor

VS Code (GitHub Copilot)

Windsurf

Available MCP Tools

Agent-slim responses

Skill resources

Structured error codes

Issues & Feedback

Requirements

Development

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages