Quickstart

From clone to a journaled paper-trading tick in about five minutes. Needs Node 20+ and an Anthropic API key. No exchange key for paper mode.

1. Install

git clone https://github.com/nirholas/perpad
cd perpad
npm install
npm run build

2. Configure an agent

{
  "name": "Tidewatcher",
  "strategy": "Trade BTC and ETH momentum on the 1h trend. Prefer holding. Use tight leverage and never risk more than the margin cap.",
  "limits": {
    "markets": ["BTC", "ETH"],
    "maxLeverage": 10,
    "marginPerTradeUsd": 100,
    "maxOpenPositions": 2,
    "maxDailyLossUsd": 50
  },
  "intervalSec": 300,
  "paper": { "startingUsd": 1000 },
  "journalPath": "journal/tidewatcher.jsonl"
}

Save it as examples/btc-eth.json (a copy ships in the repo).

3. Run one tick

export ANTHROPIC_API_KEY=sk-ant-...
node dist/cli.js run examples/btc-eth.json --once

Drop --once to loop every intervalSec.

4. Verify the journal

node dist/cli.js verify journal/tidewatcher.jsonl
# ok: 9 entries, hash chain intact

5. Go live (when you mean it)

export HL_PRIVATE_KEY=0x...        # Hyperliquid API wallet key (trades, cannot withdraw)
export HL_ACCOUNT_ADDRESS=0x...    # the master account it trades for
node dist/cli.js run examples/btc-eth.json --live --i-understand-real-funds

Use a dedicated Hyperliquid API wallet with only the funds you accept losing. Never reuse a key that controls other assets. See the security model. Try "testnet": true in the config first.

Use as a library

import { Agent, Journal, PaperVenue, HyperliquidPrices } from "perpad";

const venue = new PaperVenue(new HyperliquidPrices(), 1000);
const agent = new Agent(config, venue, new Journal("journal/a.jsonl"));
await agent.tick();