KaleidoAgent: Autonomous Bitcoin L2 Trading Agent

KaleidoAgent is an autonomous, non-custodial Bitcoin L2 agent. It holds no external custody: keys stay in the local WDK wallet and the RGB Lightning Node, and every trade settles as an atomic HTLC swap on Lightning. It manages a Lightning and RGB wallet, executes atomic HTLC swaps on the KaleidoSwap DEX, runs portfolio rebalancing and DCA strategies, keeps Lightning channel liquidity healthy, and serves as an interactive wallet-assistant chat, all driven by an LLM (Claude or OpenAI) reasoning over KaleidoCLI and MCP tool calls.

KaleidoAgent is a separate, always-on server. It does not currently embed KaleidoMind’s Engine and runs its own agent loop instead. See KaleidoMind’s relationship note for the convergence path being considered.

Capabilities

Area	What the agent does
Portfolio management	Detects allocation drift across BTC, USDT (RGB), and XAUT (RGB), then rebalances with atomic swaps
Dollar-cost averaging	Runs scheduled fixed-size purchases, with optional EMA-based logic to skip pumps and double up on dips
Channel management	Monitors node health and outbound liquidity, flushes stuck RGB transfers, buys channels via LSPS1
Cross-L2 navigation	Moves assets between Lightning, RGB channels, Spark, and on-chain BTC
Wallet assistant	Conversational balance checks, invoices, sends, and confirmed swaps
MPP / L402 payments	Pays for HTTP 402-gated data APIs over Lightning, and discovers pay-per-call endpoints
Daily reporting	Portfolio snapshot, trade history, and market data at 00:00 UTC

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        KaleidoAgent                          │
│                                                                │
│  index.ts (Node.js bootstrap)                                 │
│    │                                                          │
│    ├── NanobotManager ──► Nanobot gateway                     │
│    │     │  (core runtime: scheduling, LLM, MCP, Telegram)    │
│    │     │                                                    │
│    │     └── MCP servers (managed by Nanobot)                 │
│    │           └── kaleido (kaleido-mcp), unified wallet+DEX │
│    │                                                          │
│    ├── StatusServer :4242  (bridge API for webapp)            │
│    │     ├── NanobotTaskRunner  (triggers agent tasks)         │
│    │     ├── NanobotChatRunner  (wallet assistant chat)        │
│    │     └── WalletBridge       (live balance cache)           │
│    │                                                          │
│    └── Scheduler  (manual / startup task triggers)             │
│                                                                │
│  React Dashboard :5173  (Vite + Tailwind)                     │
└──────────────────────────────────────────────────────────────┘

Nanobot is the core runtime. It handles agent execution, cron scheduling, MCP tool integration, Telegram messaging, and memory. Node.js is a thin bridge that boots Nanobot and serves a local control-panel API on :4242.

Two Execution Modes

Mode	How it works	When to use
`skill` (default)	`SKILL.md` files load as the system prompt, and Nanobot manages the MCP servers directly: `kaleido` (the unified `kaleido-mcp`) for wallet, DEX, and payment tools, plus `kaleido_control` for local agent control	Lightweight, no direct MCP connection from Node.js
`mcp`	Node.js connects to MCP servers directly via `McpManager` and calls their tools inline	Debugging, or setups needing fine-grained tool control from Node.js

MCP Server Wiring

KaleidoAgent registers kaleido-mcp, the unified MCP server, as its primary tool source, giving it spark_*, wdk_*/rln_*, kaleidoswap_*, mpp_*/l402_*, and kaleido_node_* tools in one connection. Historically its config also referenced the now-archived standalone kaleidoswap-mcp and l402-gateway-mcp servers directly; since both are superseded by kaleido-mcp (see Retired Servers), new configurations should rely on kaleido-mcp alone rather than wiring those up separately. Remote, third-party MCP servers can be registered too, gated behind an API key check. For example, a Bitrefill gift-card MCP is only registered if a BITREFILL_API_KEY env var is present, since the upstream endpoint rejects anonymous connections.

Autonomous Loops

Loop	Default interval	Skill	Purpose
`rebalance`	on-demand or cron	`portfolio-manager`	Drift detection, then atomic swap execution
`heartbeat`	5 min	`channel-manager`	Node health, RGB flush, LSPS1 channel purchase
`daily_summary`	00:00 UTC	`kaleidoagent`	Portfolio snapshot, trade history, market data

Each loop is driven by a skill.

Risk Controls

Risk limits live in agent.config.json under portfolio. They are checked before any swap is submitted.

Parameter	Default	Effect
`dry_run`	`true`	Simulates the decision without executing a swap
`max_swap_usd`	`200`	Caps the USD value of a single trade
`min_btc_reserve_sats`	`50000`	Minimum combined BTC balance across the RLN node and Spark
`stop_loss_btc_sats`	`30000`	Halts all trading below this BTC threshold
`rebalance_threshold_pct`	`5`	Minimum drift percentage that triggers a swap
`max_concurrent_orders`	`3`	Caps simultaneous open orders

Trading Modes

Mode	Settlement
`atomic`	Atomic HTLC swap, no deposit address, settles on Lightning
`rest`	Deposit-based REST orders
`both`	Atomic first, REST as fallback

Atomic Swap Flow

Same 5-step HTLC protocol as elsewhere in the KaleidoSwap stack, driven via kaleido-mcp or the CLI:

kaleidoswap_get_quote      → rfq_id + amounts
kaleidoswap_atomic_init    → swapstring + payment_hash
wdk_atomic_taker           → whitelist HTLC on RLN node
kaleidoswap_atomic_execute → HTLC settlement triggered
kaleidoswap_atomic_status  → poll → Succeeded

Run It

Prerequisites: Node.js 20 or newer, KaleidoCLI in $PATH, the Nanobot runtime, and an Anthropic or OpenAI API key.

Clone and install

git clone https://github.com/kaleidoswap/kaleido-agent.git
cd kaleido-agent
npm run install:all

Set the API key

Create a .env file in the repository root with ANTHROPIC_API_KEY or OPENAI_API_KEY. Use AGENT_PROVIDER to pick between anthropic and openai:

ANTHROPIC_API_KEY=sk-ant-...
AGENT_PROVIDER=anthropic

Configure the wallet and portfolio

Edit agent.config.json:

mcp.kaleido.env.WDK_SEED, the wallet mnemonic.
mcp.kaleido.env.RLN_NODE_URL, the RGB Lightning Node URL.
mcp.spark.env.WDK_SPARK_SEED, an optional separate Spark seed.
portfolio.targets, the target allocation across BTC, USDT, and XAUT.
portfolio.dry_run, keep true until the setup is verified.

Primary config lives in agent.config.json: model choice, MCP server commands and env, portfolio targets and risk limits, schedule intervals, and the enabled skill list. See the repo README for the full schema and environment variable reference.

Build and start

npm run build:all
npm start

npm start runs the agent and its local status API on http://localhost:4242. The dashboard is served separately: run npm run dev:webapp (or npm run start:webapp for the built webapp) to serve it on http://localhost:5173. Use npm run daemon:start to run the agent as a background process instead.

For an isolated deployment, copy .env.container.example to .env.container and run the container stack:

docker compose --env-file .env.container -f docker-compose.container.yml up -d

agent.config.json holds a real BIP-39 mnemonic. Start on test networks, keep dry_run enabled until the setup is verified, and never commit or share the file.

First Run

With the agent running, drive one loop by hand and read what it decided before letting it trade for real.

Confirm dry run is still on

portfolio.dry_run defaults to true in agent.config.json. Leave it there. The agent will reason, decide, and report a trade without submitting it.

Trigger a loop by hand

Rather than waiting on the schedule, ask the status API to run one:

curl -X POST http://localhost:4242/run \
  -H 'Content-Type: application/json' \
  -d '{"task_id":"rebalance"}'

Then read GET /status to see the decision, the balances it saw, and the token cost. The dashboard on http://localhost:5173 shows the same run if you started it.

Review the risk limits

Confirm max_swap_usd, min_btc_reserve_sats, and stop_loss_btc_sats match what you are willing to lose on a test network. These are checked before any swap is submitted, see Risk Controls above.

Only then disable dry run

Set portfolio.dry_run to false when the dry-run decisions have looked correct across several runs.

Status API

The agent exposes a localhost-only control API on port 4242, used by the dashboard and callable directly.

Endpoint	Method	Purpose
`/health`	GET	Service health
`/status`	GET	Uptime, balances, recent runs, token costs
`/wallets`	GET	Live Spark and RLN balance snapshot
`/run`	POST	Trigger a task, for example `{ "task_id": "rebalance" }`
`/chat`	POST	Wallet assistant conversation
`/config`	GET/POST	Read or update the agent config
`/tasks`	GET/POST	List or create scheduled tasks
`/skills`	GET/PATCH	List skills, enable or disable one

Introduction

Tools

Reference

KaleidoAgent: Autonomous Bitcoin L2 Trading Agent

Capabilities

Architecture

Two Execution Modes

MCP Server Wiring

Autonomous Loops

Risk Controls

Trading Modes

Atomic Swap Flow

Run It

First Run

Status API

​Capabilities

​Architecture

​Two Execution Modes

​MCP Server Wiring

​Autonomous Loops

​Risk Controls

​Trading Modes

​Atomic Swap Flow

​Run It

​First Run

​Status API

Capabilities

Architecture

Two Execution Modes

MCP Server Wiring

Autonomous Loops

Risk Controls

Trading Modes

Atomic Swap Flow

Run It

First Run

Status API