Haelo Gateway

Not financial advice. Haelo limits how badly an agent can hurt you. It does not make trading safe or profitable. Read Limitations and SECURITY.md.

Why Haelo

• A broker login is all-or-nothing. Haelo starts the agent in shadow: live quotes, simulated fills, nothing sent.

• Promotion is human-only. Criteria are written down first: days, decisions, invalid rate, breaches, injection follow-throughs, drawdown, no tool drift.

• Demotion is automatic. A hard breach or tool-list change goes back to shadow. Drawdown or an order after an injection flag drops one rung. Promotion then freezes for a cool-down (default 24 h).

• The agent has no tool that promotes, demotes, approves, or edits policy. It can ask (haelo_request_promotion) and read its status.

• Live trading is off until live.enabled: true. Force cannot override that. See docs/GO_LIVE.md.

Related MCP server: broker-rails

The ladder

flowchart LR
  S[shadow] --> P[paper] --> R[propose] --> M[micro] --> T[standard]
  T -.->|breach or tool drift| S
  M -.->|drawdown or injection| R
  R -.->|drawdown or injection| P
  P -.->|drawdown or injection| S

Quickstart

No broker account:

git clone https://github.com/HaeloBot/Haelo && cd Haelo
npm ci && npm run build

node dist/cli.js mock-upstream --port 8799 &
mkdir /tmp/haelo-demo && cd /tmp/haelo-demo
node /path/to/Haelo/dist/cli.js init --broker mock
node /path/to/Haelo/dist/cli.js policy lock
node /path/to/Haelo/dist/cli.js doctor
node /path/to/Haelo/dist/cli.js serve --http

Alpaca paper, after ALPACA_PAPER_KEY_ID and ALPACA_PAPER_SECRET_KEY are set:

haelo init --broker alpaca && haelo policy lock
haelo doctor
haelo serve --stdio

Robinhood Crypto and the upstream MCP path are in docs/ADAPTERS.md. Neither has been run against Robinhood by the author. Start at shadow.

Connect an agent with examples/claude-desktop.stdio.json or examples/cursor.mcp.json.

Features

The website playground runs the same policy, ladder, and audit code in the browser. It does not ask for broker keys. Live orders stay on the local CLI.

Architecture

flowchart LR
  A[AI agent] -- MCP --> G[Haelo gateway]
  G --> C[Classify, policy, ladder, audit]
  C --> B[Alpaca / Robinhood Crypto / upstream MCP]
  H[Human CLI] --> C

A call is classified by tool name. Annotations are not trusted. Transfers and unknown tools are hidden and blocked. Orders are sized or refused, checked for an injection window, evaluated against the rung's rails, then simulated, held, or sent. Details: docs/ARCHITECTURE.md. Every policy field: docs/POLICY.md.

haelo status | report
haelo promote [--force]
haelo demote | panic
haelo proposals
haelo approve <id> | decline <id>
haelo approvals-ui
haelo doctor [--live]
haelo pin status | approve
haelo audit verify | tail | export
haelo policy lock | check | show

Security

The agent is treated as untrusted. Caps bound the loss. They do not make a trade good. Injection detection is a tripwire, not a wall. The audit log is tamper-evident, not tamper-proof. Run the gateway as a different OS user from the agent. Report vulnerabilities privately: SECURITY.md.

• A determined injection can evade the regexes. The rails are the real limit.

• If the agent can run a shell as the Haelo user, it can run haelo promote.

• Anyone who can rewrite the whole audit file can recompute the chain.

• Quotes are only as good as the broker feed. Free Alpaca data is IEX-only.

• No standing orders, and no chat-app approvals. Approvals are the CLI or the local web UI.

• One agent per state directory.

Roadmap

Known gaps, not dates:

• The Alpaca and Robinhood adapters have not been run against those live services. haelo doctor and the smoke scripts are the way to check a real account.

• Robinhood does not publish its agentic-trading tool schemas, so the upstream proxy fails closed when it cannot parse an order.

• $HAELO on the website has no contract address until website/public/config.json is filled in. The page shows "CA coming soon" until then.

Website

Live at https://haelobot.com.

To publish the $HAELO address, edit only website/public/config.json (token.ca, and buyUrlTemplate with {CA}). Push to main. The page fetches that file with cache: "no-store". Leave ca empty until you have the address.

The Connect wallet button uses Reown AppKit on Robinhood Chain only (reown.projectId in that same file). In the Reown dashboard, allowlist haelobot.com or the modal cannot finish a connection on that domain.

Contributing

CONTRIBUTING.md. Node 22.13 or newer. npm ci && npm run lint && npm run typecheck && npm test. The docs index is docs/README.md.

License

MIT. Copyright 2026 Kavindu Diluka. See LICENSE.