NavaClaw

NavaClaw is a DeFi-focused agent harness based on NanoClaw. It enables autonomous AI agents to trade on-chain, remember what they learn, and run on a schedule, including signing transactions, executing swaps, and managing positions.

NavaClaw is a TypeScript monorepo that ships as a single server: plug in a model provider, point it at a chain, give it skills, and let it run.

Set up NavaClaw locally for the Developer Preview. Inspect the repository and existing configuration first. Ask me to choose the model provider, chain, channel, and in-memory or Postgres persistence before editing config. Keep every secret in environment variables and never print its value. Set EXECUTION_MODE=dry-run, do not add a private key, do not enable direct execution, and do not activate a scheduled skill without asking me separately. Install dependencies, build, type-check, test, start the server, and verify both /health and /ready. Report the files changed, checks run, remaining manual credential steps, and anything you deliberately left disabled.

Overview

What You Get

• Multi-chain execution. Protocol-specific execution skills (e.g., verified-swap for Uniswap) handle calldata generation, Nava verification, and broadcast internally. Add a new protocol by creating a skill, no code changes required.
• Nava verification. NavaClaw can ask Nava Guardian for a policy verdict before execution. The preview version of Nava Guardian is verdict-only and advisory; NavaClaw remains responsible for enforcing the verdict before it signs or broadcasts an action. See Execution safety.
• Skills on demand. Drop a SKILL.md file into ./skills/ and the agent learns a new capability on the fly. Skills are listed in a compact catalog; the agent reads them via cat when needed, not injected into the prompt. Hot-reloaded, no restart needed.
• Cron and heartbeat. Schedule recurring jobs with cron expressions. Skills can declare their own schedules in frontmatter.
• Memory. Typed memory tool with search, recall, and observe actions. Backed by Postgres + pgvector for persistent semantic search, or zero-config in-memory mode for development. Memory is accessed on demand, not injected into every prompt.
• Channels. Talk to your agent via Telegram or Slack. Channel plugins are composable and easy to extend.
• Any model. Claude, GPT, Gemini, Ollama, OpenRouter. Swap providers without changing your agent config.

Architecture

Data flow: Inbound message (channel) enters the pipeline (model call, tools) and produces an outbound reply (channel). The heartbeat triggers jobs on cron schedules. On-chain execution is handled by protocol-specific skills that bundle calldata generation, Nava verification, and broadcast into self-contained scripts. Skills are read on demand via bash. Memory is queried via the memory tool.

Setup

Prerequisites

• Node.js 22+ (nvm install 22)
• pnpm (npm install -g pnpm)
• Foundry (optional, for on-chain reads via cast-read)
• Docker (optional, for Postgres persistence; omit DATABASE_URL for in-memory mode)

Quick Start

The fastest path is the interactive setup wizard, which handles deps, builds, provider config, channels, skills, and generates config.json + .env for you.

:::warning Direct execution is an explicit opt-in

Keep EXECUTION_MODE=dry-run while you configure providers, channels, policies, and scheduled skills. The preview version of Nava Guardian is verdict-only and advisory, so NavaClaw is responsible for keeping an action paused unless the exact proposed action receives an approved verdict. Enable direct only after you have reviewed the execution safety boundary, tested the complete flow, and deliberately accepted the signing and broadcast risk.

:::

Claude Code

git clone --recursive git@github.com:navalabs-dev/nava-claw.git && cd nava-claw

Open a Claude Code session and run:

/setup

The wizard should ask for the provider, chain, channel, and persistence choice. Review its proposed changes before accepting them. Keep dry-run mode enabled and decline private-key, direct-execution, and schedule activation steps during the initial setup. After it finishes, run the build, type checks, tests, and both health probes shown below.

Cursor

Open the project in Cursor and use the copyable setup prompt at the top of this page. Cursor picks up the repository setup rule, while the prompt supplies the required safety defaults and verification steps.

Manual

git clone --recursive git@github.com:navalabs-dev/nava-claw.git && cd nava-claw
pnpm install && pnpm build
cp .env.example .env   # Fill in your API keys and secrets
# Create config.json (see Configuration)
EXECUTION_MODE=dry-run pnpm --filter @nava-claw/server start

The server starts on http://localhost:4747. Health check at /health.

curl --fail http://localhost:4747/health
curl --fail http://localhost:4747/ready

Docker (with Postgres Persistence)

cp .env.example .env   # Fill in your API keys
# Set EXECUTION_MODE=dry-run in .env
# Create config.json (see Configuration)
docker compose up

This starts Postgres (pgvector) + the app. Memory, cron jobs, and sessions persist across restarts. To run without persistence, just omit DATABASE_URL from .env and run the server directly.

Development

pnpm build          # Build all packages (TypeScript project references)
pnpm check          # Type-check without emitting
pnpm test           # Run all tests (Vitest)
pnpm clean          # Clean build artifacts

API Endpoints

Configuration

NavaClaw uses two config sources: secrets in .env and everything else in config.json.

Environment Variables

See .env.example for the full list. Key ones:

config.json

{
  "port": 4747,
  "agents": [
    {
      "id": "default",
      "name": "Nava",
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "identity": "You are Nava, a trading assistant running in dry-run mode. Never sign or broadcast an action unless the operator has deliberately enabled direct execution and the exact action has an approved Guardian verdict. Treat a missing, pending, malformed, unavailable, rejected, or timed-out verdict as blocked. Never reveal secrets."
    }
  ],
  "providers": {
    "anthropic": {
      "baseUrl": "https://api.anthropic.com",
      "apiKey": { "env": "ANTHROPIC_API_KEY" },
      "api": "anthropic-messages",
      "models": [
        { "id": "claude-sonnet-4-6", "name": "Sonnet 4.6", "contextWindow": 1000000, "supportsToolUse": true }
      ]
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": { "botToken": { "env": "TELEGRAM_BOT_TOKEN" } }
      }
    }
  },
  "chain": { "id": 42161, "name": "Arbitrum One" },
  "tools": {
    "bash": {
      "enabled": true,
      "allow": {
        "commands": ["curl", "cast-read", "cat", "jq", "grep", "head", "echo"],
        "paths": ["./skills"]
      }
    },
    "typed": true
  }
}

Secrets use the { "env": "VAR_NAME" } pattern. Never hardcode keys in config.

Supported Chains

Writing Skills

Skills are markdown files that teach the agent new behaviors. Drop a SKILL.md into ./skills/<name>/ and it’s live on the next heartbeat cycle.

Directory Structure

skills/
  core/           Auto-enabled (cast-read, testnet, mcporter)
  reference/      Supplementary docs (Uniswap Trading API, Uniswap driver)

Skill Format

---
name: my-strategy
description: My custom trading strategy
tags: trading
schedule: "0 */2 * * *"    # Optional: runs every 2 hours
---
 
# My Strategy
 
## Goal
 
Describe one bounded strategy and the result it should produce.
 
## Inputs
 
List the required market data, wallet state, and operator parameters.
 
## Decision rules
 
State the entry, exit, sizing, and stop conditions as testable rules.
 
## Safety
 
- Start in dry-run mode.
- Never sign or broadcast unless direct execution is enabled and Guardian has
  approved the exact action.
- Stop on a missing, pending, malformed, unavailable, rejected, or timed-out
  verdict.
- Ask before changing a schedule, chain, credential, or policy.
 
## Output
 
Report the proposed action, Guardian result, execution state, and any blocked
condition without exposing secrets.

How Skills Work

• Skills are listed in a compact catalog; the agent reads them via cat when needed, not injected into the prompt.
• Hot-reloaded, no restart needed.
• Skills can declare their own schedules in frontmatter using cron expressions.
• The heartbeat runner triggers scheduled skills on their cron schedule.
• Protocol-specific execution skills (e.g., verified-swap for Uniswap) bundle calldata generation, Nava verification, and broadcast into self-contained scripts.

Channels

Talk to your NavaClaw agent via Telegram or Slack. Channel plugins are composable and easy to extend.

Telegram

1. Create a bot via @BotFather and get the bot token.
2. Set TELEGRAM_BOT_TOKEN in .env.
3. Enable in config.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": { "botToken": { "env": "TELEGRAM_BOT_TOKEN" } }
      }
    }
  }
}

Slack

1. Create a Slack app and get the bot token.
2. Set SLACK_BOT_TOKEN in .env.
3. Enable in config.json:

{
  "channels": {
    "slack": {
      "enabled": true,
      "accounts": {
        "default": { "botToken": { "env": "SLACK_BOT_TOKEN" } }
      }
    }
  }
}