§ 1 · OVERVIEW

Kuroda is a self-hosted trading engine that turns natural-language strategies into on-chain actions on Solana, using the Claude API as its reasoning layer. It runs entirely on the user's machine. No hosted service, no custodial wallet, no telemetry.

The entire system is a single Docker Compose stack: a Python worker, a local SQLite database, and a small web UI served at localhost:3000.

§ 2 · REQUIREMENTS

• — Docker 24+ and Docker Compose v2
• — An Anthropic API key with access to Claude Sonnet 4.5 or newer
• — A Solana wallet with a small amount of SOL for fees and positions
• — ~500 MB of free disk for the local DB and receipt store
• — Linux, macOS, or WSL2 on Windows

§ 3 · INSTALL

$ git clone https://github.com/KURODAPI/KURODA
$ cd KURODA
$ cp .env.example .env
$ nano .env            # add your keys
$ docker compose up -d
$ open http://localhost:3000

Healthcheck: curl localhost:3000/api/health should return {"status":"idle"}.

§ 4 · PROJECT LAYOUT

kuroda/
├── docker-compose.yml
├── .env                 # your keys (never commit)
├── spellbooks/
│   └── alpha.txt        # your strategy, plain text
├── data/
│   ├── kuroda.db        # SQLite: positions, receipts
│   └── receipts/        # per-trade JSON logs
├── worker/
│   ├── main.py          # main loop
│   ├── parser.py        # spellbook → rules
│   ├── feeds.py         # data source adapters
│   ├── reasoner.py      # Claude API client
│   ├── executor.py      # Solana tx builder
│   └── guardrails.py    # hard-rule enforcement
└── ui/
    └── ...              # Next.js dashboard

§ 5 · CONFIGURATION (.env)

# Claude
ANTHROPIC_API_KEY=sk-ant-...
KURODA_MODEL=claude-sonnet-4-5
KURODA_MAX_TOKENS_PER_TICK=15000

# Solana
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_WALLET_PRIVATE_KEY=...       # base58
SOLANA_NETWORK=mainnet              # or devnet

# Engine
KURODA_TICK_INTERVAL=300            # seconds between scans
KURODA_SPELLBOOK=./spellbooks/alpha.txt
KURODA_DRY_RUN=true                 # start here, always
KURODA_MAX_POSITION_PCT=5           # global hard cap
KURODA_DAILY_LOSS_LIMIT_PCT=3       # kill-switch

Always start with KURODA_DRY_RUN=true. In dry-run mode the full pipeline runs but no transactions are signed. Flip to false only after a week of clean receipts.

§ 6 · THE TICK LOOP

Every KURODA_TICK_INTERVAL seconds the worker runs one tick. A tick is five stages. If any stage fails, the tick is aborted and nothing is signed.

[1] INGEST    feeds.py pulls fresh data from all sources
              listed in the spellbook (news, on-chain, TA).

[2] REASON    reasoner.py sends context + spellbook
              + recent receipts to Claude. Claude
              returns a structured ActionProposal:
              {action, symbol, size_pct, reason, confidence}.

[3] VALIDATE  guardrails.py runs hard rules against
              the proposal. Any violation → reject.

[4] EXECUTE   executor.py builds, signs, and submits
              the Solana tx via Jupiter aggregator.
              Waits for confirmation.

[5] RECORD    writes a receipt (JSON) and updates
              positions in SQLite.

§ 7 · SPELLBOOK FORMAT

A spellbook is a plain-text file. The parser extracts two things: hard rules (machine-enforced) and soft guidance (passed to Claude as the system prompt).

Hard rules are any line that matches these patterns:

never more than N% of capital per trade
never trade on {weekends|monday|...}
stop at -N%
take profit at +N%
daily loss limit N%
whitelist: SOL, JTO, PYTH, ...
blacklist: <token list>

Everything else in the file is treated as soft guidance. Claude reads it to understand intent, but the guardrails layer never lets Claude violate a hard rule — even if Claude "thinks" it should.

Example alpha.txt:

watch the top 50 SOL ecosystem tokens.
if claude judges a piece of news is real
(not shilling, not recycled), open a position.

take profit at +30%.
stop at -15%.
never more than 5% of capital per trade.
daily loss limit 3%.
never trade on weekends.

§ 8 · THE REASONER CONTRACT

Claude is called once per tick with a tool-use schema. It must return exactly one of:

// tool: propose_action
{
  "action": "open" | "close" | "hold",
  "symbol": "JTO",
  "size_pct": 4.1,
  "reason": "string, 1-3 sentences",
  "confidence": 0.0 - 1.0,
  "evidence": [
    { "source": "url or feed id",
      "excerpt": "short quote" }
  ]
}

The evidence field is mandatory. A proposal with no evidence is auto-rejected before guardrails. This is the single most important anti-hallucination defense in the system.

§ 9 · RECEIPTS

Every tick — whether it results in a trade or not — produces a receipt at data/receipts/{timestamp}.json:

{
  "tick_id": "2026-04-07T08:14:22Z",
  "model": "claude-sonnet-4-5",
  "tokens_in": 8420,
  "tokens_out": 612,
  "feeds_scanned": ["coingecko","birdeye","x"],
  "proposal": { ... },
  "guardrails": { "passed": true, "checked": [...] },
  "tx": { "signature": "5xR...", "status": "confirmed" },
  "pnl_after": { "unrealized": 0.031, "realized": 0.12 }
}

Receipts are append-only. Nothing in Kuroda ever mutates or deletes a receipt. If you want a clean slate, move the folder aside.

§ 10 · GUARDRAILS

Guardrails are enforced in Python, not in the prompt. Claude cannot talk its way past them. Current checks:

• — position size ≤ KURODA_MAX_POSITION_PCT
• — token is on whitelist (if defined) and not on blacklist
• — daily realized + unrealized loss within limit
• — day-of-week / time-of-day restrictions
• — proposal has non-empty evidence array
• — confidence ≥ minimum threshold (default 0.6)
• — RPC round-trip < 2s (else abort, retry next tick)

§ 11 · DEBUGGING

$ docker compose logs -f worker   # live worker logs
$ docker compose exec worker \
  python -m kuroda.repl            # interactive REPL
$ sqlite3 data/kuroda.db \
  "select * from positions;"      # inspect state

The REPL lets you replay a historical tick against a different spellbook — useful for dialing in rules without risking capital.

§ 12 · KILL SWITCH

Three ways to stop the wizard, in order of severity:

1. Pause — touch data/PAUSE. The worker finishes the current tick and then sleeps until the file is removed. Positions are held.
2. Unwind — touch data/UNWIND. The worker closes all open positions at market, then pauses.
3. Halt — docker compose down. Immediate stop. Open positions remain on-chain; you manage them manually.

§ 13 · WARNINGS

This is experimental software. Run in dry-run for at least a week. Then run on devnet. Then run with an amount you are fully prepared to lose. Only then consider scaling.

LLMs hallucinate. The guardrails layer exists because the reasoner layer will, occasionally, be confidently wrong. Set your hard rules tight. Review your receipts.

No warranty. MIT license. You are running this on your machine, with your keys, against your funds. We cannot help you if something goes wrong at 3am.