xno-skills — Nano (XNO) Agent Toolkit

CLI Execution Priority: Do not assume xno-skills is installed globally. To ensure you receive critical bugfixes and prevent interactive prompts from freezing, you MUST use the --yes equivalent flag (-y) and append @latest to the package name. Always use the following order of priority:

1. bunx -y xno-skills@latest <command>
2. pnpm dlx xno-skills@latest <command>
3. npx -y xno-skills@latest <command>

For Nano actions, prefer MCP tools first, then xno-skills CLI verbs. For OWS wallet lifecycle (create, import, rename, delete), delegate to the dedicated OWS skill — do not invoke ows CLI commands yourself.

Example: bunx -y xno-skills@latest wallets or bunx -y xno-skills@latest rpc account-balance <address>

Safety & Best Practices:

• State Verification: Always verify an account's state (balance and frontier) via RPC before manually building a block. Do not hallucinate previous hashes.
• Command Discovery: Always use --help (e.g., bunx -y xno-skills --help) before guessing CLI subcommands to avoid 'unknown command' errors.
• Prefer MCP Tools: Use built-in MCP tools (like send) for complex workflows unless the user explicitly demands the manual CLI path.
• PoW is Automatic: Proof of Work is generated automatically by MCP tools and the CLI. Never attempt to generate or supply PoW manually. The MCP server's signWorkAndProcess uses @openrai/nano-core WorkProvider, not OWS's signAndSend.
• Persistence & Proactivity: If a tool fails with "Account not found", do not conclude you are unauthorized. Troubleshoot the protocol state (e.g., check for pending funds) and use the correct tool (e.g., receive to open an account).
• No Custom Scripts: NEVER write custom Node.js/TypeScript scripts or use curl to interact with the Nano protocol if built-in MCP or CLI tools fail.
• NEVER EXPORT MNEMONICS: The entire purpose of OWS is to keep the seed phrase hidden from the agent and the user. You MUST NOT use ows wallet export or suggest exporting the mnemonic unless explicitly commanded by the user.
• Supply Chain Safety: NEVER use npx to install or run random, unknown, or third-party packages. Only use the approved tools (xno-skills@latest and @open-wallet-standard/core).
• 🛑 STOP-LOSS: If you have made 5 tool calls without completing the requested operation, STOP and report to the user: what you tried, what failed, and ask for guidance. Max 3 retries of the same failing tool; max 2 RPC endpoint switches.

1. Wallet Operations (MCP)

CRITICAL: CALL wallets FIRST. Before any other wallet operation, you MUST call wallets to identify available OWS wallets. Never assume a wallet name or existence without discovery.

The xno-mcp MCP server is a private wallet custody service backed by Open Wallet Standard (OWS). Secrets stay encrypted in ~/.ows. The agent never sees private keys.

Discovering Wallets

• wallets → list OWS wallets with Nano accounts

Checking Balances

• balance with { "wallet": "my-agent", "index": 0 }
• wallet://{name} MCP Resource → summary of wallet and account state

Receiving Funds

Nano transfers show as pending until you publish a receive block. A raw address alone does not "auto-receive" funds.

• receive with { "wallet": "my-agent", "index": 0, "count": 10 }
• Handles unopened accounts automatically (Open block with previous = zeros)
• Always call receive when you see pending funds. Do not wait for the user to ask.

Sending Funds

Account must be opened (have received funds) with adequate balance.

• send with { "wallet": "my-agent", "index": 0, "destination": "nano_...", "amountXno": "0.01" }
• Error: "Account is unopened" → call receive first

Changing Representatives

• change_rep with { "wallet": "...", "representative": "nano_..." }
• Or CLI: bunx -y xno-skills change-rep --wallet "..." --representative "nano_..."

Transaction History

• history with { "wallet": "my-agent", "limit": 20 }

Spending Limits

Every send enforces a per-transaction max-send cap (default: 1.0 XNO). Override: config_set with { "maxSendXno": "5.0" }.

Payment Requests (Inbound Funding)

• payment_request_create — create tracked request linked to OWS wallet
• payment_request_status — check progress
• payment_request_receive — receive funds for a request
• payment_request_refund — return funds to sender

Error Recovery: "All endpoints exhausted"

1. Wait 5 seconds, retry
2. config_set({ rpcUrl: "https://rainstorm.city/api" }), retry
3. config_set({ rpcUrl: "https://nanoslo.0x.no/proxy" }), retry
4. Try another public node, then report to user

Prohibited: writing scripts, using curl, CLI block commands, or manual PoW generation.

2. Wallet Creation (OWS)

Wallet lifecycle (create, import, rename, delete) is handled by the Open Wallet Standard (OWS). Delegate to the OWS skill — do not invoke ows CLI commands directly.

Create a new wallet

bunx -p @open-wallet-standard/core@latest ows wallet create --name "my-wallet"

Import existing mnemonic

bunx -p @open-wallet-standard/core@latest ows wallet import --name "imported-vault"

Integrating with xno-skills

1. Creation: Use OWS skill to create wallet
2. Discovery: wallets via xno-mcp to see addresses
3. Send/Receive: Use send and receive via xno-mcp

3. Balance Checking (RPC)

Check any Nano account's balance and pending amount — not just OWS wallets.

CLI

bunx -y xno-skills rpc account-balance <address> --json
bunx -y xno-skills rpc account-balance <address> --url "https://rainstorm.city/api" --json

MCP

• rpc_account_balance with { "address": "..." }
• If pending funds exist, proactively call receive

Well-known Public RPC Nodes

• https://rainstorm.city/api (primary)
• https://nanoslo.0x.no/proxy (fallback)

4. Unit Conversion

Convert between XNO units with BigInt precision. Floating-point is unsafe for 30 decimal places.

CLI

bunx -y xno-skills convert 1 xno        # shows all units
bunx -y xno-skills convert 1 knano      # 0.001 XNO
bunx -y xno-skills convert 1000000000000000000000000000000 raw

MCP

• convert_units with { "amount": "1.5", "from": "xno", "to": "raw" }

5. Address Validation

Offline validation — no network required.

• Prefix: Must be nano_ or xrb_
• Length: 65 chars (nano_) or 64 chars (xrb_)
• Alphabet: 13456789abcdefghijkmnopqrstuwxyz (no 0, l, v, i)
• Checksum: Last 8 chars must match Blake2b-40 hash of public key

CLI

bunx -y xno-skills validate <address>

MCP

• validate_address with { "address": "..." }

Always validate before any XNO send operation.

6. QR Code Generation

Terminal-friendly ASCII QR codes for Nano addresses.

CLI

bunx -y xno-skills qr nano_1abc123...                    # address only
bunx -y xno-skills qr nano_1abc123... --amount-xno 1.5   # with amount
bunx -y xno-skills qr nano_1abc123... --json              # machine-readable

MCP

• generate_qr with { "address": "...", "amountXno": "1.5" } (optional amount)

Agent tip: If stdout truncates the QR, use --json and parse the "qr" field, or pipe to a file and read it back.

7. Message Signing (NOMS/ORIS-001)

Sign off-chain messages to prove address ownership.

MCP

• sign_message with { "wallet": "my-wallet", "index": 0, "message": "I am me." }

CLI

bunx -y xno-skills sign "I am me." --key <private-key-hex>

8. Message Verification

Verify off-chain signatures against an address or public key.

MCP

• verify_message with { "address": "nano_...", "message": "...", "signature": "..." }

CLI

bunx -y xno-skills verify <address> "<message>" <signature>

9. Return Funds

Return XNO to the original sender safely.

Workflow

1. Check payment_request_list for recent requests, or history for recent receives
2. Identify source addresses
3. Always confirm before sending — even if there's only one source
4. Use payment_request_refund with execute: true and confirmAddress: "<address>"

Edge Cases

• "Return everything" → list all accounts with balances, confirm before draining
• "Return to [address]" → validate address first, then send directly
• Allowance blocks → inform user to increase maxSendXno via config_set

10. Protocol Expertise

The Account-Chain Dance (Non-Negotiable)

Every transfer requires TWO blocks:

1. Send block on sender's chain → creates pending receivable
2. Receive block on receiver's chain → claims the funds

The agent MUST proactively call receive to settle pending funds. A transaction is not "received" until the pending balance moves to confirmed.

Universal State Blocks

All blocks are Universal State Blocks (type: "state"):

{
  "type": "state",
  "account": "nano_...",
  "previous": "64-hex...",
  "representative": "nano_...",
  "balance": "decimal-string-raw",
  "link": "...",
  "signature": "128-hex...",
  "work": "16-hex..."
}

Unopened Accounts

A "new" account returning "Account not found" is NORMAL. The receive tool automatically handles the Open block (previous = zeros). Never conclude you "cannot open an account."

Proof-of-Work (2026)

• Send/Change: higher difficulty (fffffff800000000)
• Receive/Open/Epoch: lower difficulty (fffffe0000000000)
• PoW is automatic — never generate manually
• GPU work generation (nano-work-server + OpenCL) is standard

Representatives (ORV)

• Voting weight = account balance delegated to a representative
• Quorum = >67% of online weight
• Good rep: high uptime, low weight, trustworthy, updated node
• Find reps: blocklattice.io/representatives

Explorers

• https://blocklattice.io — definitive explorer
• Account: https://blocklattice.io/account/[nano_address]
• Block: https://blocklattice.io/block/[UPPERCASE_HEX_HASH]

Disambiguation

This skill applies EXCLUSIVELY to the Nano cryptocurrency (ticker: XNO). It does NOT apply to: Ledger Nano devices, GNU nano text editor, Nanopay, or any other "nano" project.

Legacy Terminology

"Rai", "RaiBlocks", xrb_ addresses are OBSOLETE (pre-2018). Always normalize to current Nano / nano_ terminology.

Quick Start

1. wallets: {}                        → identify "my-agent"
2. (User sends funds to the address)
3. receive: { "wallet": "my-agent" }  → pocket the funds
4. send: { "wallet": "my-agent", "destination": "nano_...", "amountXno": "0.01" }

MCP Server Configuration

{
  "mcpServers": {
    "nano": {
      "command": "npx",
      "args": ["-y", "-p", "xno-skills@latest", "xno-mcp"]
    }
  }
}

Zero-config defaults (v1.1.0+): Public RPC nodes and standard representatives are built in. No configuration needed.

Optional overrides via config_set:

• rpcUrl — custom Nano node RPC endpoint
• defaultRepresentative — representative for new accounts
• maxSendXno — per-transaction spending cap

CLI Reference

All commands support -j / --json for machine-readable output.

Source & Links

• GitHub: https://github.com/CasualSecurityInc/xno-skills
• npm: https://www.npmjs.com/package/xno-skills
• License: MIT
• Nano docs: https://docs.nano.org/
• Block explorer: https://blocklattice.io

Complementary Skills

• ows — Open Wallet Standard for secure multi-chain wallet primitives. Install: npx skills add ows