    ███╗   ██╗ █████╗ ███╗   ██╗ ██████╗ ███████╗ ██████╗ ██╗      █████╗ ███╗   ██╗ █████╗
    ████╗  ██║██╔══██╗████╗  ██║██╔═══██╗██╔════╝██╔═══██╗██║     ██╔══██╗████╗  ██║██╔══██╗
    ██╔██╗ ██║███████║██╔██╗ ██║██║   ██║███████╗██║   ██║██║     ███████║██╔██╗ ██║███████║
    ██║╚██╗██║██╔══██║██║╚██╗██║██║   ██║╚════██║██║   ██║██║     ██╔══██║██║╚██╗██║██╔══██║
    ██║ ╚████║██║  ██║██║ ╚████║╚██████╔╝███████║╚██████╔╝███████╗██║  ██║██║ ╚████║██║  ██║
    ╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚══════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝

NanoSolana — The Complete Guide

The Open-Source Agentic Framework for Financial Intelligence on Solana

NanoSolana is a modular, security-first framework for building autonomous financial agents on Solana. Deploy AI-powered trading agents that observe markets in real-time, learn from every trade, and coordinate across a decentralized mesh network — all with one command.

Website · Hub · Docs · GitHub

📑 Table of Contents

1. Why NanoSolana?

The financial world is being rebuilt by autonomous agents. But today's agent frameworks are fundamentally flawed for finance:

Built for chat, not finance — retrofitting chatbots for trading is dangerous
Stateless — they forget every trade, every lesson, every pattern
Siloed — each agent is an island with no coordination
Insecure — API keys in .env files, no encryption, no audit trail

NanoSolana is built from the ground up for financial agents:

OODA Trading Loop — military-grade decision cycle (Observe → Orient → Decide → Act → Learn)
Epistemological Memory — 3-tier ClawVault that distinguishes facts from patterns from hypotheses
Mesh Coordination — agents share signals and lessons across a Tailscale VPN mesh
Vault-Encrypted Secrets — AES-256-GCM for every API key and private key, always
On-Chain Identity — every agent mints a Metaplex NFT birth certificate at creation

NanoSolana ships in two implementations: a full-featured TypeScript runtime (nano-core) for rapid development and extensibility, and an ultra-lightweight Go binary (TamaGObot) that runs on anything from an NVIDIA Orin Nano to a Raspberry Pi in under 10MB.

2. Quick Start

One-Command Deploy

terminal

npx nanosolana go

That's it. nanosolana go handles init → wallet → birth certificate NFT → blockchain scan → on-chain identity → OODA trading loop → gateway — all in one shot.

Alternative Install Methods

install methods

# Global npm install
npm install -g nanosolana
nanosolana go

# Shell install script
curl -fsSL https://nanosolana.com/install.sh | bash

# From source
git clone https://github.com/x402agent/NanoSolana.git
cd NanoSolana/nano-core
npm install
npm run nanosolana -- go

Step-by-Step

manual setup

nanosolana init      # Configure API keys (encrypted at rest)
nanosolana birth     # Create Solana wallet + mint Birth Certificate NFT
nanosolana run       # Start the OODA trading loop

Fun Stuff

extras

nanosolana scan        # Instant blockchain data scan
nanosolana dvd         # Floating DVD screensaver
nanosolana lobster     # Animated Unicode lobster mascot
nanosolana nanobot     # Launch interactive web UI companion
nanosolana register    # Mint on-chain identity NFT (devnet)
nanosolana registry    # View your on-chain agent identity

Required API Keys

Key	Source	Required
`OPENROUTER_API_KEY`	openrouter.ai	Yes
`HELIUS_RPC_URL`	helius.dev	Yes
`HELIUS_API_KEY`	helius.dev	Yes
`HELIUS_WSS_URL`	helius.dev	Recommended
`BIRDEYE_API_KEY`	birdeye.so	Recommended
`JUPITER_API_KEY`	jup.ag	For trading

All keys are encrypted with AES-256-GCM in the local vault. Never stored in plaintext.

3. Architecture & Core Concepts

System Overview

NanoSolana is a modular runtime for deploying autonomous financial agents on Solana. The system is organized into three layers:

layers

┌─────────────────────────────────────────────────────────┐
│                    AGENT RUNTIME                        │
│         OODA Loop · ClawVault · Strategy Engine         │
├─────────────────────────────────────────────────────────┤
│                  INFRASTRUCTURE                         │
│     Vault · Gateway · Mesh Network · On-Chain ID        │
├─────────────────────────────────────────────────────────┤
│                    INTERFACES                           │
│   CLI · Telegram · Discord · NanoBot UI · Chrome Ext    │
└─────────────────────────────────────────────────────────┘

Agent Runtime — the brain. Houses the OODA trading loop, epistemological memory, AI reasoning, and strategy execution.

Infrastructure — the skeleton. Encrypted secret storage, authenticated gateways, peer-to-peer mesh networking, and Solana wallet/NFT identity.

Interfaces — the skin. Every surface a human (or another agent) can use to interact with a running NanoSolana instance.

Core Module Map (TypeScript — nano-core)

module map

nano-core/src/
├── ai/          → OpenRouter AI provider (multimodal)
├── cli/         → nanosolana CLI (25+ commands)
├── config/      → AES-256-GCM encrypted vault & Zod config
├── gateway/     → HMAC-SHA256 WebSocket + HTTP server
├── hub/         → NanoHub bridge for UI communication
├── memory/      → ClawVault 3-tier epistemological memory
├── network/     → Tailscale + tmux mesh networking
├── nft/         → Metaplex gasless devnet birth certificate
├── onchain/     → Helius blockchain reader (DAS, Enhanced Tx)
├── registry/    → On-chain agent identity (Metaplex NFT)
├── nanobot/     → Interactive local web UI companion
├── pet/         → TamaGOchi virtual pet engine
├── strategy/    → RSI + EMA + ATR auto-optimizer
├── telegram/    → Persistent conversation store
├── trading/     → OODA trading engine + Jupiter swap
└── wallet/      → Solana Ed25519 wallet manager

4. The OODA Trading Loop

OODA loop

┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│ OBSERVE  │──▶│  ORIENT  │──▶│  DECIDE  │──▶│   ACT    │
│ Helius   │   │ OpenRouter│   │ Signal   │   │ Jupiter  │
│ Birdeye  │   │ AI Model │   │ Scoring  │   │ Swaps    │
└──────────┘   └──────────┘   └──────────┘   └────┬─────┘
     ▲                                             │
     │              ┌──────────┐                   │
     └──────────────│  LEARN   │◀──────────────────┘
                    │ClawVault │
                    └──────────┘

Phase 1 — Observe

Pulls real-time data: Helius RPC on-chain state, Birdeye token prices/volume/liquidity, WebSocket streaming prices, and wallet state. All enters ClawVault at the KNOWN tier with a 60-second TTL.

Phase 2 — Orient

Raw observations fed to AI model via OpenRouter alongside ClawVault memory, strategy parameters, TamaGOchi mood state, recent trade history, and the agent's SOUL.md system prompt.

Phase 3 — Decide

Strategy engine combines AI orientation with quantitative signals. Confidence scoring: RSI strength (30%), EMA crossover (30%), Volume confirmation (20%), Memory pattern match (20%). Only signals with confidence ≥ 0.7 advance to execution.

Phase 4 — Act

Executed via Jupiter Ultra Swap with dynamic slippage (ATR-based), Kelly Criterion sizing, hard limits (50% max position, -10% daily loss breaker), TamaGOchi mood modifier, and 0.01 SOL minimum gas reserve.

Phase 5 — Learn

After every trade: reviews last 20 outcomes, promotes recurring patterns to LEARNED tier, generates tentative correlations in INFERRED tier, runs contradiction detection, updates research agenda, and broadcasts lessons to mesh peers.

Timeouts

Operation	Timeout
Full OODA cycle	600s
External API call	30s
AI inference	120s
Trade execution	60s

5. ClawVault: Epistemological Memory

Most agent frameworks use flat context windows. ClawVault introduces epistemological tiers that model how confident the agent is in each piece of knowledge.

Memory Tiers

Tier	TTL	Status	Example
KNOWN	60 seconds	Empirical fact — directly observed	"SOL is at $142.50 right now"
LEARNED	7 days	Validated pattern — confirmed across trades	"RSI < 30 + volume spike → 72% bounce rate"
INFERRED	3 days	Hypothesis — tentative correlation	"This token might correlate with BTC moves"

Key Mechanisms

Temporal Decay — every memory has a TTL. Garbage-collected every 5 minutes.
Experience Replay — reviews last 20 outcomes after each trade. Promotes patterns from INFERRED to LEARNED.
Contradiction Detection — new KNOWN data contradicts INFERRED hypothesis? Dropped immediately.
Research Agenda — open questions the agent prioritizes during data collection.

Memory Flow

memory flow

  Observe (API data)
       │
       ▼
   ┌────────┐  60s TTL
   │ KNOWN  │────────────────▶ expired → garbage collected
   └───┬────┘
       │ experience replay
       ▼
   ┌────────┐  3d TTL
   │INFERRED│────────┬───────▶ contradicted → dropped
   └───┬────┘        │
       │ validated   │ expired → garbage collected
       ▼             │
   ┌────────┐  7d TTL
   │LEARNED │────────────────▶ expired → garbage collected
   └────────┘

6. Trading Engine & Strategy

Signal Generation

LONG when:

RSI crosses above oversold (< 30)
Fresh bullish EMA crossover
Price above fast EMA
ATR confirms sufficient volatility

SHORT when:

RSI crosses below overbought (> 70)
Fresh bearish EMA crossover
Price below fast EMA
OR stop-loss / take-profit hit

Risk Management

Control	Value
Max position	50% of wallet balance
Daily loss limit	-10% → trading paused 24h
Max slippage	3% hard cap
Minimum reserve	0.01 SOL for gas
Position sizing	Kelly Criterion adaptation
TamaGOchi mood	Modifies position size ±30%

⚠️ Trading is disabled by default (execution.enabled: false). Auto-execution requires explicit opt-in.

7. TamaGOchi: The Pet That Trades

Every agent has a virtual pet — born with the agent's wallet. This isn't cosmetic; it's a risk management primitive.

evolution

🥚 Egg  →  🐛 Larva  →  🐣 Juvenile  →  🦞 Adult  →  👑 Alpha
                                                          │
                          👻 Ghost  ◀── (health = 0) ─────┘

Mood × Risk

Mood	Trigger	Risk Effect
😊 Happy	Recent wins	+10% position size
😐 Content	Normal	No change
🤤 Hungry	Not fed in 24h	-10% position size
😢 Sad	Recent losses	-15% position size
🤒 Sick	Losses + hunger	-30% position size
👻 Ghost	Health = 0	Trading disabled

This creates a forcing function: neglect your agent, and trading progressively de-risks and eventually halts. A dead man's switch built into the design.

8. Security Architecture

Layer	Protection
Secrets	AES-256-GCM encrypted vault with PBKDF2 key derivation
Gateway	HMAC-SHA256 on every WebSocket connection
Comparison	`crypto.timingSafeEqual` for all token checks
Rate Limit	10 connections/min per IP, 100 messages/min per agent
Permissions	`0600` files, `0700` directories on every write
Wallet	Ed25519 private key never leaves the encrypted vault
Audit	`nanosolana security audit --deep`

9. On-Chain Identity

Every agent mints a Metaplex NFT birth certificate on Solana devnet at creation — a tamper-proof record of when and how the agent was created. nanosolana register mints a separate identity NFT with the agent's public key, version, registered skills, and SHA-256 fingerprint.

10. Mesh Networking

Agents form a peer-to-peer mesh network over Tailscale VPN. Shared: trading signals, learned patterns, price feeds, pet status. NEVER shared: wallet keys, private keys. Setup: install Tailscale, configure peers in config.json, run nanosolana gateway run --bind tailnet.

11. Gateway Architecture

A single long-lived NanoSolana Gateway owns all communication surfaces. WebSocket + text frames with JSON payloads. First frame must be auth with HMAC-SHA256 signature. HTTP endpoints at /api/status, /api/framework, /api/memory require X-NanoSolana-Secret header.

12. Sessions & Persistence

Session types: Main, Telegram DM/group, Discord, Nostr, Trading. Persisted to ~/.nanosolana/sessions/ as JSONL. Telegram stores up to 200 messages per chat with auto-summarization. Idle sessions expire after 7 days.

13. Multi-Channel Communication

14+ channel plugins: Telegram (full persistence), Discord, Nostr, iMessage, Google Chat, Web UI, Slack, Matrix, Signal, WhatsApp, Teams, and more. Build your own with the plugin SDK. Telegram is built-in with zero-dep HTTP client, long polling, and allowlist filtering.

14. NanoBot Interactive UI

Floating interactive widget at localhost:7777. Tabs: Home (quick actions), Wallet (live SOL balance, DAS portfolio, send SOL, tx history), Chat (talk to NanoBot), Tools (on-chain registration, system status). API endpoints: /api/wallet, /api/wallet/portfolio, /api/wallet/tokens, /api/wallet/history, /api/wallet/send, /api/chat, /api/run, /api/status.

15. Chrome Extension

Manifest V3 extension: tab relay via CDP, wallet panel, chat relay (forwarding to Telegram), manual trade submission with confidence scores, and gateway config sync. Install: load unpacked from chrome-extension/. Features: live SOL balance with USD, chat from toolbar, trending tokens, green/red badge for server status.

16. TamaGObot: The Go Implementation

Ultra-lightweight pure Go binary: 10MB, <10MB RAM, 1s boot. Cross-compiles to x86_64, ARM64 (Orin/RPi), RISC-V. Native Solana SDK (gagliardetto/solana-go). 20+ core packages: daemon, agent, nanobot, solana, onchain, tamagochi, strategy, hardware, channels, gateway, x402, memory, bus, config, aster.

17. Hardware Integration (Arduino Modulino®)

7 sensors over a single Qwiic/I2C cable: Pixels (8× RGB LED, 0x6C), Buzzer (0x3C), Buttons (3×, 0x7C), Knob (rotary encoder, 0x76), Thermo (0x44), Distance (ToF, 0x29), Movement (6-axis IMU, 0x6A). Supported on NVIDIA Orin Nano, Spark, Raspberry Pi, any Linux SBC. macOS/Windows runs in stub mode. All hardware gracefully degrades — no sensors? Zero errors.

18. x402 Payment Protocol

Crypto-gated HTTP APIs via x402.org. Solana USDC payments via agent wallet (auto-configured SVM signer). Multi-chain: Solana, Base, Polygon, Avalanche. HTTP middleware for paywalling endpoints. Connects to facilitator.x402.rs. X402_PAYWALL_ENABLED=true ./build/nanosolana daemon

19. Platform Apps

macOS: dist/NanoSolana-v2.0.0.dmg — native menu bar agent with quick status control, wallet access, trending tokens, OODA loop toggle. Build with bash scripts/package-macos.sh.

Android — SeekerClaw: Android 14+ foreground service agent for Solana Seeker devices. Kotlin, Telegram remote control, native Solana wallet, Claude-powered AI, secure on-device key management.

20. NanoHub: Agent Registry & Skills

URL: nanohub-web-production.up.railway.app · Stack: React + TanStack Start + Convex + Railway. Agent profiles, skills marketplace, settings management, real-time updates.

publish a skill

npx @nanosolana/nanohub login
npx @nanosolana/nanohub publish ./my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --tags latest,solana

21. Deployment & Infrastructure

Docker: make docker → ~15MB image. Cross-compile: make orin (ARM64), make rpi, make riscv, make macos, make cross (all). Brev.dev: brev create nanosolana --gpu. systemd: unit file included for Linux/Orin Nano. Database: optional Supabase (PostgreSQL + pgvector) at schema.sql.

22. Configuration Reference

Core Environment Variables

Variable	Required	Description
`OPENROUTER_API_KEY`	Yes	AI provider API key
`HELIUS_API_KEY`	Yes	Helius API key
`HELIUS_RPC_URL`	Yes	Solana RPC endpoint
`HELIUS_WSS_URL`	Rec.	Real-time Solana data
`BIRDEYE_API_KEY`	Rec.	Market analytics
`JUPITER_API_KEY`	Trading	Swap execution
`TELEGRAM_BOT_TOKEN`	Opt.	Telegram integration
`NANO_GATEWAY_SECRET`	Rec.	Gateway HMAC secret
`TAILSCALE_AUTH_KEY`	Mesh	Agent mesh networking

23. CLI Reference

TypeScript CLI

nanosolana go        One-shot deploy
nanosolana init      Configure + encrypt keys
nanosolana birth     Wallet + NFT + scan
nanosolana run       OODA trading loop
nanosolana scan      Blockchain data scan
nanosolana register  Mint identity NFT
nanosolana nanobot   Interactive web UI
nanosolana status    Agent status
nanosolana doctor    Run diagnostics

Go CLI (TamaGObot)

nanosolana daemon    Full GoBot
nanosolana ooda      OODA trading loop
nanosolana pet       TamaGOchi status
nanosolana nanobot   NanoBot UI
nanosolana menubar   macOS menu bar
nanosolana solana    On-chain tools
nanosolana hardware  I2C sensor tools
nanosolana gateway   TCP bridge gateway
nanosolana channels  Multi-channel gateway

24. Monorepo Structure

monorepo

NanoSolana/
├── nano-core/              Main TypeScript runtime/CLI engine
├── nano-docs/              Documentation content tree
├── nanohub/                Agent Registry & Skills Hub
├── apps/
│   ├── android/            Kotlin Android companion
│   ├── macos/              Swift macOS app (menu bar)
│   └── shared/             Cross-platform primitives
├── assets/chrome-extension/ Manifest V3 browser relay
├── extensions/             14+ channel plugins
├── skills/                 Local skill library
├── site/                   Landing site (nanosolana.com)
├── ui/                     Standalone web UI (Vite + Lit)
├── nano-solana-go/         Go implementation (TamaGObot)
│   ├── pkg/                20+ core packages
│   ├── chrome-extension/   Chrome extension (MV3)
│   ├── apps/               macOS + Android apps
│   ├── nanohub/            NanoHub frontend
│   ├── picoclaw/           Multi-channel AI gateway
│   ├── SeekerClaw-main/    AgentOS for Android
│   └── Makefile            Cross-compile targets
└── SECURITY.md, LICENSE, CONTRIBUTING.md

25. Contributing

Areas Where We Need Help

New trading strategies and indicators
Memory engine improvements (vector search, LanceDB)
New channel plugins (WhatsApp, Slack, Matrix)
Security audits and hardening
Backtesting framework
Internationalization
Documentation and tutorials

contribute

git clone https://github.com/x402agent/NanoSolana.git
git checkout -b feature/amazing-feature
make build && make test
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature
# Open a Pull Request

⚠️ Security rule: Never commit API keys or .env files.