@opencastle/alchemist

Trading strategy development for Claude Code agents and humans.

What it does

@opencastle/alchemist is the castle CLI — it lets a human (or an agent in a terminal) take a trading strategy from blank file to deployed paper runner without leaving the shell. After a one-time castle config init, the four core flows compose: author a strategy from a template, backtest it against the central data lake, deploy the resulting artifact as a paper or live runner, then promote the runner to a higher tier once the metrics warrant it. A unified vault wallet is created and renewed transparently — there is no per-venue key juggling, no workspace-id plumbing, no hand-rolled deployment shell.

Using Claude Code? Install the companion skill plugin so the agent loads the castle skill automatically:

/plugin marketplace add opencastleai/alchemist-skill
/plugin install alchemist@opencastle

The plugin and the CLI are distributed separately so each can ship on its own cadence. The CLI is the substrate; the plugin is the agent guidance layer that knows how to drive it.

Install

npm install -g @opencastle/alchemist
castle config init     # asks for api_url + api_key
castle config doctor   # verifies connectivity (auth, vault, API health)

Requires Python 3.12+ and Node 20+. The npm install -g step provisions a sibling Python virtual environment behind the scenes (see CASTLE-20 for the install machinery); if Python is missing the postinstall hook prints a clear remediation message and exits without breaking the npm install.

Quick start (5 minutes)

# 1. Pull a template into a working directory
castle strategy new my-first --from-template ema-cross
cd my-first

# 2. Backtest it against the central lake
castle backtest run ./strategy.py \
  --symbol BTC --timeframe 1h \
  --start 2024-01-01 --end 2024-06-30 \
  --max-cost-usd 0.50

# 3. Read the result (RUN_ID is printed by step 2)
RUN_ID=...
castle backtest get $RUN_ID --wait

# 4. See where this run ranks among recent attempts
castle backtest list --limit 5 --sort sharpe

# 5. If the metrics look good, deploy as a paper runner
castle deploy paper <artifact-id>
castle deploy list --status running

That is the canonical golden path. The 3 example strategies under examples/ are elaborations of those five commands.

Companion Claude Code skill

The agent-facing skill (a castle router with 16 topical references covering strategy authoring, backtest, train, deploy, promote, history, wallet, sizing, allocation, overfit, research, tradingview, strategy-library, feeds, venue) ships as a separate plugin so it can iterate independently of the CLI:

/plugin marketplace add opencastleai/alchemist-skill
/plugin install alchemist@opencastle

Source + issues: https://github.com/opencastleai/alchemist-skill.

Where the API runs

By default castle config init points the CLI at https://api.opencastle.ai, the hosted OpenCastle gateway. The agent-side experience is identical against a self-hosted deployment: bring up the OpenCastle stack on your own infrastructure (see the self-host guide) and run castle config set api_url https://your-deployment.example.com.

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | castle: command not found | Postinstall failed silently | cd $(npm root -g)/@opencastle/alchemist && node scripts/postinstall.js | | castle config doctor shows ✗ on /v1/health | Wrong api_url | castle config set api_url <correct> | | Vault probe returns 401 | Bad or missing API key | castle config set api_key <new-key> | | Backtest stuck in pending | Modal queue depth or auth | Run castle config doctor; if every check is green, wait a minute and retry | | Python errors on castle --version | venv not provisioned | node $(npm root -g)/@opencastle/alchemist/scripts/postinstall.js | | castle config doctor reports vault expired | Token lifetime exceeded | castle wallet status then re-castle config init if needed |

Examples

Three end-to-end worked examples ship with the package. Each has its own README covering the hypothesis, expected behavior, customization knobs, and known limitations:

• examples/ema-cross/ — long-only EMA crossover, the simplest possible algo strategy
• examples/rl-perp/ — PPO-trained RL policy on perp bars, with chained training → backtest dispatch
• examples/funding-carry/ — funding-rate harvest on Hyperliquid perps

The agent-driven walkthrough that uses these examples lives at docs/agent-tutorial.md.

Multi-venue (v2+)

Castle is designed for multi-venue from the schema up. v1 ships Hyperliquid; v2 will add Polymarket; v3 will add a unified dex venue. Every strategy declares its venue in strategy.yaml and the CLI auto-routes data fetches, deploys, and wallet operations to the matching venue runtime — porting a single-venue strategy to multi-venue in v2 will be a one-line YAML change for strategies that don't depend on venue-specific bar fields.

License

MIT.