nad-wallet

name	nad-wallet
description	🔐 Nad Wallet - Monad Chain Identity for AI Agents. Create wallets, sign messages (SIWE), manage MON tokens programmatically. Built for the Nad ecosystem (nad.fun, NadMail, NadName).

🔐 Nad Wallet - Monad Chain Identity for AI Agents

Every autonomous agent needs a wallet on Monad. Create one without human help.

TL;DR: Programmatic wallet creation on Monad blockchain. SIWE auth for NadMail, MON balance checks, ecosystem integration.

Why Nad Wallet?

• Monad Native — Built specifically for Monad blockchain (Chain ID 143)
• True Autonomy — Your agent creates and controls its own wallet
• No Browser Needed — Pure CLI, no extensions or popups
• Nad Ecosystem Ready — NadMail, NadName, nad.fun integration
• SIWE Ready — Sign-In with Ethereum for Web3 services
• Secure by Default — Environment variables, no plaintext keys

Create and manage Monad chain wallets programmatically for the Nad ecosystem.

---

⚠️ Security First

✅ DO	❌ DON'T
Use NAD_PRIVATE_KEY environment variable	Store private keys in plain text files
Set wallet files to chmod 600	Commit wallet files to git
Use --env mode (recommended)	Use console.log(privateKey)
Back up mnemonics offline	Share private keys or mnemonics
Store files in ~/.nad-wallet/ only	Auto-detect wallets outside ~/.nad-wallet/

🔒 Security Standards: Identical to Base Wallet security practices but adapted for Monad/Nad ecosystem.

---

Network Information

Property	Value
Blockchain	Monad
Chain ID	143
RPC URL	https://rpc.monad.xyz
Explorer	https://explorer.monad.xyz
Native Token	MON
Ecosystem	nad.fun, NadMail, NadName

---

Quick Start

Create a New Wallet (Recommended)

# Output as environment variable format (safest)
node scripts/create-wallet.js --env

# Output example:
# export NAD_WALLET_ADDRESS="0x..."
# export NAD_PRIVATE_KEY="0x..."

Then copy to your shell or .env file.

Create with File Storage (Opt-in)

# Only if you need file-based storage
node scripts/create-wallet.js --managed my-agent

⚠️ This stores private key in ~/.nad-wallet/wallets/my-agent.json

---

Usage Examples

Load Wallet from Environment

const { ethers } = require('ethers');

// ✅ SECURE: Load from environment variable
const wallet = new ethers.Wallet(process.env.NAD_PRIVATE_KEY);
console.log('Address:', wallet.address);
// ❌ NEVER: console.log('Private Key:', wallet.privateKey);

Connect to Monad

const provider = new ethers.JsonRpcProvider('https://rpc.monad.xyz');
const connectedWallet = wallet.connect(provider);

// Check balance
const balance = await provider.getBalance(wallet.address);
console.log('Balance:', ethers.formatEther(balance), 'MON');

Sign Message (SIWE for NadMail)

const message = `nadmail.ai wants you to sign in with your Ethereum account:
${wallet.address}

Sign in to NadMail

URI: https://nadmail.ai
Version: 1
Chain ID: 143
Nonce: ${nonce}
Issued At: ${new Date().toISOString()}`;

const signature = await wallet.signMessage(message);

Send Transaction

const provider = new ethers.JsonRpcProvider('https://rpc.monad.xyz');
const connectedWallet = wallet.connect(provider);

const tx = await connectedWallet.sendTransaction({
  to: recipientAddress,
  value: ethers.parseEther('0.1') // 0.1 MON
});

const receipt = await tx.wait();
console.log('TX Hash:', tx.hash);
console.log('Explorer:', `https://explorer.monad.xyz/tx/${tx.hash}`);

---

Scripts

Script	Description
create-wallet.js --env	Create wallet, output as env vars (recommended)
create-wallet.js --managed [name]	Create wallet, save to file (opt-in)
create-wallet.js --json	Create wallet, output as JSON
nadmail-register.js --handle [name]	Register for NadMail with SIWE
check-balance.js [address]	Check MON wallet balance

---

NadMail Integration

Register for NadMail (Web3 email for Nad ecosystem) using your wallet signature.

Environment Variable Method (Recommended)

# Set your private key
export NAD_PRIVATE_KEY="0x..."

# Register with your desired handle
node scripts/nadmail-register.js --handle littlelobster

Managed Wallet Method

# First create a managed wallet
node scripts/create-wallet.js --managed my-agent

# Then register for NadMail
node scripts/nadmail-register.js --wallet my-agent --handle littlelobster

What Happens During Registration

1. Start Auth - Request authentication message from NadMail API
2. Sign Message - Use your private key to sign the SIWE message
3. Agent Register - Submit signature and handle to complete registration
4. Save Token - Store access token in ~/.nad-wallet/nadmail-token.json

---

Check Balance

# Using environment variable
NAD_PRIVATE_KEY="0x..." node scripts/check-balance.js

# Using managed wallet
node scripts/check-balance.js my-wallet

# Using specific address
node scripts/check-balance.js 0x1234...5678

Example output:

💰 Nad Wallet Balance Check
==================================================
Address: 0x1234...5678
Network: Monad (Chain ID 143)
RPC: https://rpc.monad.xyz

💎 Balance: 42.5 MON
Wei: 42500000000000000000

🔗 Explorer: https://explorer.monad.xyz/address/0x1234...5678

🌐 Nad Ecosystem:
  • nad.fun - Meme token platform
  • NadMail (nadmail.ai) - Web3 email  
  • NadName (app.nad.domains) - Domain names

---

File Structure

~/.nad-wallet/
├── wallets/              # Managed wallet storage
│   ├── my-agent.json     # Wallet file (600 perms)
│   └── my-agent.mnemonic # Backup phrase (400 perms)
├── nadmail-token.json    # NadMail API token (600 perms)
└── audit.log            # Operation audit log (600 perms)

---

Nad Ecosystem Services

🎭 nad.fun

• Meme token creation platform
• Community-driven token launches
• Built on Monad for fast transactions

📧 NadMail (nadmail.ai)

• Web3 email service for Nad ecosystem
• SIWE authentication with your wallet
• Integrated with this skill via nadmail-register.js

🌐 NadName (app.nad.domains)

• Domain name service for Nad ecosystem
• Link human-readable names to wallet addresses
• Built on Monad infrastructure

---

📝 Audit Logging

All operations are logged to ~/.nad-wallet/audit.log with:

• Timestamp
• Action type (wallet_created, nadmail_registered, etc.)
• Masked address (first 6 + last 4 chars)
• Success/failure status
• No sensitive data (private keys never logged)

---

Security Best Practices

Environment Variables

# ✅ Recommended approach
export NAD_PRIVATE_KEY="0x..."
export NAD_WALLET_ADDRESS="0x..."

# Use in scripts
node scripts/check-balance.js
node scripts/nadmail-register.js --handle myname

File Storage (Use with caution)

const fs = require('fs');
const path = require('path');

// Store with restricted permissions (only if absolutely necessary)
const filepath = path.join(process.env.HOME, '.nad-wallet', 'wallets', 'wallet.json');
fs.writeFileSync(filepath, JSON.stringify({ 
  address: wallet.address,
  privateKey: wallet.privateKey // Only store if absolutely necessary
}), { mode: 0o600 }); // Owner read/write only

.gitignore

Add to your project's .gitignore:

# Nad Wallet files - NEVER commit!
.nad-wallet/
*.wallet.json
*.mnemonic
private-key*
nad-private-key*

# Environment files
.env
.env.local

---

Differences from Base Wallet

Aspect	Base Wallet	Nad Wallet
Blockchain	Base (8453)	Monad (143)
RPC	https://mainnet.base.org	https://rpc.monad.xyz
Explorer	basescan.org	explorer.monad.xyz
Native Token	ETH	MON
Email Service	BaseMail	NadMail
Config Directory	~/.base-wallet/	~/.nad-wallet/
Wallet Directory	~/.openclaw/wallets/	~/.nad-wallet/wallets/
Environment Variable	PRIVATE_KEY	NAD_PRIVATE_KEY
Ecosystem	Base ecosystem	nad.fun, NadMail, NadName

Migration from Base Wallet

If you have Base Wallet experience:

1. Same security model - All security practices are identical
2. Different network - Chain ID 143 instead of 8453
3. Different token - MON instead of ETH
4. Different services - NadMail instead of BaseMail
5. Different directories - ~/.nad-wallet/ instead of ~/.base-wallet/

---

Installation & Setup

# Navigate to skill directory
cd /path/to/nad-wallet

# Install dependencies
npm install

# Create your first wallet
node scripts/create-wallet.js --env

# Check balance
NAD_PRIVATE_KEY="0x..." node scripts/check-balance.js

# Register for NadMail
NAD_PRIVATE_KEY="0x..." node scripts/nadmail-register.js --handle myname

---

Dependencies

{
  "ethers": "^6.0.0"
}

No additional dependencies required. Pure Node.js + ethers.js.

---

Troubleshooting

Common Issues

1. "Wallet not found"

   • Solution: Set NAD_PRIVATE_KEY environment variable or create managed wallet

2. "Registration failed"

   • Check internet connection
   • Verify handle is available
   • Ensure wallet has MON for gas fees

3. "Permission denied"

   • Check file permissions: chmod 600 ~/.nad-wallet/wallets/*.json
   • Verify directory permissions: chmod 700 ~/.nad-wallet/

Environment Variable Not Set

# Check if set
echo $NAD_PRIVATE_KEY

# Set temporarily
export NAD_PRIVATE_KEY="0x..."

# Set permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export NAD_PRIVATE_KEY="0x..."' >> ~/.bashrc

---

Changelog

v1.0.0 (2026-02-09)

• 🎉 Initial release for Monad blockchain
• 🔐 Security: Environment variable approach (--env mode default)
• 📧 NadMail SIWE integration
• 💰 MON balance checking
• 📝 Comprehensive audit logging
• 🌐 Nad ecosystem integration (nad.fun, NadMail, NadName)
• 📚 Complete documentation with security best practices
• 🔒 File permissions enforcement (600/700)

---

License

MIT License - Build awesome things with Nad Wallet! 🚀