Content
# xno-skills
[](https://www.npmjs.com/package/xno-skills)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
A CLI, MCP server, and AI skills for [Nano](https://nano.org/) (XNO). Built on top of [Open Wallet Standard (OWS)](https://github.com/open-wallet-standard/core) for secure key custody.
## Design Overview
```text
CLI/MCP transaction command
↓
build unsigned Nano state block
↓
OWS signs the block hash
↓
choose work root + threshold
↓
local PoW, or remote work_generate → local fallback
↓
attach signature + work
↓
RPC process
```
xno-skills separates block construction, signing, proof of work, and publication. The CLI and MCP server use the same transaction code. The transaction code reads the account frontier and balance, builds the state block, and asks OWS to sign it without exposing wallet keys. It selects the Nano work root and threshold from the block subtype.
PoW runs locally through `nano-rspow-node` when recommended. Otherwise, xno-skills tries the configured `work_generate` endpoints and falls back to local generation if they fail. It then attaches the signature and work nonce and publishes the block with RPC `process`. Send and representative-change blocks use the send threshold. Receive and open blocks use the lower receive threshold. Open blocks use the account public key as their work root.
## Agent Skills
[](https://smithery.ai/servers/casualsecurityinc/xno-skills)
[](https://skills.sh/casualsecurityinc/xno-skills)
Built-in skill for Personal AI Agents (OpenClaw etc.) and humans with AI Coding Assistants (Claude Code, Cursor, etc.) alike:
```bash
npx skills add CasualSecurityInc/xno-skills -g
# or non-interactively, i.e. for agent use:
npx -y skills add CasualSecurityInc/xno-skills -g -y --all
```
### Claude Code
```
/plugin marketplace add CasualSecurityInc/xno-skills
/plugin install xno-skills@casual-security-inc
```
> [!IMPORTANT]
> If you installed skills from this repository before May 4, 2026, you have 11 individual `nano-*` skills that have been consolidated into a single `nano` skill. Remove the old ones first:
> ```bash
> npx skills remove nano-block-lattice-expert nano-check-balance nano-convert-units nano-create-wallet nano-generate-qr nano-mcp-wallet nano-request-payment nano-return-funds nano-sign-message nano-validate-address nano-verify-message -g -y
> ```
> Then reinstall as above.
Available skills:
- `nano`: Wallet ops, balance, send/receive, QR codes, address validation, unit conversion, payment requests, refunds, block-lattice protocol expertise, and more — all in one skill. Uses `xno-mcp` MCP tools first, falls back to `xno-skills` CLI.
## CLI
### Installation & Upgrades
To install or upgrade the CLI, AI agent skills, and wallet dependencies to the latest version, run:
```bash
npm install -g xno-skills && npx -y skills add CasualSecurityInc/xno-skills -g -y --all
xno-skills --help
```
To pin to the current stable release instead:
```bash
npm install -g xno-skills@4.6.0 && npx -y skills add CasualSecurityInc/xno-skills -g -y --all
```
### Wallet Operations
| Command | Description |
|---|---|
| `wallets [options]` | List wallets that have Nano accounts |
| `balance [options]` | Show balance and pending amount |
| `receive [options]` | Receive pending blocks |
| `send [options]` | Send Nano |
| `change-rep [options]` | Submit a change representative block |
| `submit-block [options]` | Sign and submit a prepared block hex |
| `history [options]` | Show transaction history |
### Utilities
| Command | Description |
|---|---|
| `info [options]` | Discover the current state and representative of any Nano account |
| `convert [options] <amount> <from>` | Convert between XNO units |
| `qr [options] <address>` | Generate a QR code for a Nano address |
| `validate [options] <input>` | Validate a Nano address or block hash |
### Cryptography & Signing
| Command | Description |
|---|---|
| `sign [options] <message>` | Sign a NOMS message with a private key |
| `verify [options] <address> <message> <signature>` | Verify a NOMS message signature |
### Advanced & RPC
| Command | Description |
|---|---|
| `rpc` | Query a Nano node RPC |
| `rpc probe-caps [url]` | Probe one or more comma-separated RPC URLs for JSON RPC, ledger-read, process, and remote PoW support |
| `block` | Build unsigned Nano state blocks for manual/expert workflows |
### System
| Command | Description |
|---|---|
| `diag` | Show version, environment, effective RPC/work URLs, and local PoW recommendation without network probes |
| `mcp` | Start the MCP server or view configuration instructions |
All commands support `-j` / `--json` for machine-readable output.
Use `diag` for local configuration diagnostics. Use `rpc probe-caps <effective-work-url>` when you need live endpoint capability checks, including `work_generate` support.
Wallet lifecycle (create, import, rename, delete) is managed by [OWS](https://github.com/open-wallet-standard/core). `xno-skills` bundles OWS as a dependency — no separate install needed. See the [OWS quick-start](https://openwallet.sh/#quickstart) for terminal usage, or install OWS agent skills with `npx skills add open-wallet-standard/core@ows`.
## MCP Server
Exposes Nano wallet functions as tools for AI agents (Claude Desktop, Cursor, Codex, etc.). MCP resources (`xno-wallet://` URIs) are served but require client-side `resources/read` support — not yet available in OpenCode ([#15535](https://github.com/anomalyco/opencode/issues/15535)).
**Preferred** (global install — avoids `npx` concurrency handshake failures):
```bash
npm install -g xno-skills@4.6.0
```
```json
{
"mcpServers": {
"nano": {
"command": "xno-skills",
"args": ["mcp"]
}
}
}
```
**Fallback** (if global install is not possible):
```json
{
"mcpServers": {
"nano": {
"command": "npx",
"args": ["-y", "-p", "xno-skills@4.6.0", "xno-mcp"]
}
}
}
```
### Client Setup Examples
<details>
<summary>Codex</summary>
```bash
# Preferred (after npm install -g xno-skills@4.6.0):
codex mcp add nano \
-c sandbox_mode="danger-full-access" \
-c 'sandbox_permissions=["network-access"]' \
-- xno-skills mcp
# Fallback:
codex mcp add nano \
-c sandbox_mode="danger-full-access" \
-c 'sandbox_permissions=["network-access"]' \
-- npx -y -p xno-skills@4.6.0 xno-mcp
```
</details>
<details>
<summary>Claude Desktop (<code>claude_desktop_config.json</code>)</summary>
```json
{
"mcpServers": {
"nano": {
"command": "xno-skills",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary>OpenCode (<code>~/.config/opencode/opencode.json</code>)</summary>
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"nano": {
"type": "local",
"command": ["xno-skills", "mcp"],
"enabled": true
}
}
}
```
</details>
<details>
<summary>Gemini CLI (<code>~/.gemini/settings.json</code>)</summary>
```json
{
"mcpServers": {
"nano": {
"command": "xno-skills",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary>Antigravity (<code>~/.gemini/antigravity/mcp_config.json</code>)</summary>
```json
{
"mcpServers": {
"nano": {
"command": "xno-skills",
"args": ["mcp"]
}
}
}
```
</details>
<details>
<summary>VS Code (<code>.vscode/mcp.json</code>)</summary>
```json
{
"servers": {
"nano": {
"type": "stdio",
"command": "xno-skills",
"args": ["mcp"]
}
}
}
```
</details>
## Library
For using `xno-skills` as a TypeScript library, see [LIBRARY.md](./LIBRARY.md).
## Security Notes
- **Never share your seed or private keys.** Anyone with access can fully control your wallet.
- **Store seeds securely.** Use hardware wallets or encrypted storage — never in plain text or version control.
- **Address validation.** Always validate addresses before sending. Nano addresses include checksums.
- **Unit precision.** Nano uses 30 decimal places. Always use string-based conversion to avoid floating-point errors.
## Development
```bash
npm install
npm test
npm run build
```
## Releasing
See `RELEASING.md`.
## Similar Projects
- [kilkelly/nano-currency-mcp-server](https://github.com/kilkelly/nano-currency-mcp-server) — MCP server for Nano with a simple per-transaction send limit
- [strawberry-labs/berrypay-cli](https://github.com/strawberry-labs/berrypay-cli) — Nano wallet CLI for AI agents with payment processing and auto-sweep
## License
MIT
