Vaultlane HL Copy Trading Bot for perpetuals

Vaultlane is a follower stack—not a black-box signal seller. You nominate one source wallet, define capital allocation policy, and let the pipeline translate each sourced fill into a compliant Hyperliquid order with NAV-aware sizing, leverage guards, and optional paper execution.

Built in TypeScript with @nktkas/hyperliquid, structured logging via ts-logger-pack, and a WebSocket fill stream that reconnects with a predictable linear backoff.

---

What professionals care about here

1. NAV-linked sizing — Every mirrored slice scales by your clearinghouse equity versus the source wallet, multiplied by ALLOCATION_FACTOR, then clipped by EXPOSURE_CAP_PCT so one aggressive foreign ticket cannot consume your whole book.

2. Gear discipline — Isolated leverage observed on the source leg is capped by MAX_GEAR before updateLeverage runs.

3. Operational modes — Flip PAPER_MODE=true to exercise WebSocket decoding, deduplication, and sizing math without signing trades.

4. Separation of concerns — hl/ handles transport + market reads; pipeline/ owns policy; diag/ owns logging adapters compatible with Logger from ts-logger-pack.

---

Quick start

npm install
cp .env.example .env
npm run watch

Ship build:

npm run build && node dist/index.js

---

Configuration reference

Key	Meaning
BOT_SECRET_KEY	Signing key for your follower account
FOLLOW_SOURCE_WALLET	0x address whose fills you ingest
HYPERLIQUID_TESTNET	true routes to HL test infrastructure
ALLOCATION_FACTOR	Additional scalar on NAV-based sizing
MAX_GEAR	Hard ceiling on leverage mirrored
MIN_ORDER_USD	Ignore slices smaller than this notional
EXCLUDED_COINS	Pipe-separated blocklist (example: `DOGE
PAPER_MODE	Skip exchange.order, still logs pipeline
EXPOSURE_CAP_PCT	Max slice notional vs your NAV

---

Playbook

1. Fund testnet sub-account → enable HYPERLIQUID_TESTNET=true.
2. Paper-run against a volatile source for a session; validate logs.
3. Disable paper, keep MIN_ORDER_USD high until comfortable.
4. Tighten EXCLUDED_COINS for markets you refuse to warehouse.

---

Legal / risk

Derivatives are not suitable for all investors. Past fills of a source wallet do not guarantee future performance. This repository is educational software; deploy only capital you can lose entirely.