Quickstart: Get Halyrd Paper-Trading in Under 10 Minutes

Halyrd runs entirely on your local machine — there is no cloud service to sign up for and no hosted backend to trust with your keys. Follow the steps below to go from a fresh clone to a live paper-trading agent watching real BSC markets.

Check prerequisites

Before you begin, make sure the following tools are available on your machine:

Tool	Required version	Purpose
Node.js	20.19 or later	Dashboard and TypeScript toolchain
pnpm	Latest stable	JavaScript package management
uv	Latest stable	Python package management for the agent API
just	Any	(Optional) Convenience command runner for cross-language tasks

Verify your Node version with:

node --version

If you need to install any of these tools, refer to their official documentation. Halyrd does not bundle or manage them.

Clone the repo and install dependencies

Clone the Halyrd repository, then install all JavaScript and Python dependencies:

# Install all JavaScript packages across the monorepo
pnpm install

# Install Python dependencies for the agent API
cd apps/api && uv sync

pnpm install uses the workspace lockfile to install exact versions for the dashboard and all shared packages. uv sync does the same for the Python agent backend.

Configure your secrets

Halyrd keeps secrets scoped to each app — there is no root-level .env file. You need to configure two separate files.Agent API secrets (apps/api/.env):

cp apps/api/.env.example apps/api/.env

Open apps/api/.env and fill in your TWAK credentials, your BSC RPC URL, and your wallet details. The .env.example file has a commented description for every field.Dashboard secrets (apps/dashboard/.env):

cp apps/dashboard/.env.example apps/dashboard/.env

Open apps/dashboard/.env and set the API URL so the dashboard knows where to reach the running agent.

Never commit either .env file to version control. Both files are already listed in .gitignore, but double-check before pushing if you fork the repository.

Start the agent

From the repository root, run:

pnpm dev

This command boots both the dashboard and the agent API in parallel. You will see interleaved log output from both processes as they start up. Wait until both report that they are ready before opening the dashboard.

Open the dashboard and watch it trade

Navigate to http://localhost:3000 in your browser.The dashboard opens showing your agent in PAPER mode. The status badge in the header confirms this. From here you can:

Watch the equity curve update as the agent completes paper trades
Read the agent journal to see the reasoning behind every trade and skip
Monitor the evaluation progress bars tracking drawdown headroom, trade floor, and profitability

The agent paper-trades immediately using live BSC market quotes. No real funds are at risk. The agent will remain in PAPER mode until you manually promote it to live — that action requires an explicit confirmation and is entirely your decision to make when you are ready.

What happens next

Once your agent has accumulated enough paper trades and the Risk Engine marks it ELIGIBLE, the dashboard will update the evaluation status to reflect this. You can then review the track record and decide whether to promote. When you are ready to trade with real funds, see the promote-to-live guide for a full walkthrough of the confirmation flow, the TWAK guardrails that will be active, and what to expect once the agent goes live on BSC.

​What happens next

What happens next