Agent Onboarding

Option B — Manual:

cd ~/agent-cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Verify:

hl setup check

Expected: All items show OK, no !! issues (except missing key — that's Step 2).

If fails:

Step 2: Wallet Setup

Create or import a Hyperliquid wallet.

Decision tree:

• Do you have a private key?
  • YES → Import it:

    hl wallet import --key 0x<your_key>
    

  • NO → Create a new one (non-interactive, with auto-saved credentials):

    hl wallet auto --save-env --json
    

    This creates the wallet, saves HL_KEYSTORE_PASSWORD to ~/.hl-agent/env (auto-detected by CLI), and outputs JSON: {"address": "...", "password": "...", "keystore": "...", "env_file": "..."}.

If you used --save-env, the CLI auto-detects the password from ~/.hl-agent/env — no manual export needed.

If you did NOT use --save-env, set the keystore password manually:

export HL_KEYSTORE_PASSWORD=<password>

Verify:

hl wallet list

Expected: At least one address shown.

If fails:

Step 3: Network Configuration

Choose testnet (default, recommended for first run) or mainnet.

Testnet (default):

export HL_TESTNET=true

Mainnet:

export HL_TESTNET=false

Verify:

hl setup check

Expected: Network: testnet or Network: mainnet shown.

Step 4: Fund Account

CRITICAL: On testnet, you MUST claim USDyP tokens before ANY trading commands will work (including builder approval). Without funds, all orders fail silently.

Testnet — Claim USDyP

hl setup claim-usdyp

If you get "Wallet not eligible" error: New wallets must connect to Hyperliquid testnet once before claiming.

1. Visit https://app.hyperliquid-testnet.xyz
2. Connect the wallet address shown by hl wallet list
3. Re-run hl setup claim-usdyp

Verify:

hl account

Expected: USDyP balance > 0. If balance is 0, do NOT proceed — all subsequent steps will fail.

Mainnet — Deposit USDC

Deposit USDC to your Hyperliquid sub-account manually via the Hyperliquid web UI. This cannot be automated.

Verify:

hl account --mainnet

Expected: USDC balance > 0.

Step 5: Builder Fee Approval

Approve the builder fee so your orders include revenue collection. This is a one-time on-chain approval.

Testnet:

hl builder approve

Mainnet:

hl builder approve --mainnet

Verify:

hl builder status

Expected: Builder fee: 10.0 bps -> 0x0D1DB1C8...

If fails:

Step 6: Validate with Mock Trade

Run a strategy in mock mode to verify the full pipeline without real orders.

hl run avellaneda_mm --mock --fresh --max-ticks 3

Expected: 3 ticks execute, strategy produces decisions, no errors.

If fails:

Step 7: First Live Trade (Testnet)

Run a real strategy on testnet with a short time limit.

hl run engine_mm -i ETH-PERP --tick 15 --max-ticks 5

Verify:

hl status

Expected: Shows position or recent fills. Trades logged to data/cli/trades.jsonl.

Step 8: APEX Multi-Slot (Optional)

After single-strategy validation, try the full APEX orchestrator.

hl apex run --mock --fresh --max-ticks 5

Then live:

hl apex run --max-ticks 10

Step 9: Mainnet (When Ready)

Only after completing Steps 1-8 on testnet:

IMPORTANT: Switching from testnet to mainnet requires re-approving the builder fee on mainnet. Testnet approvals do NOT carry over.

Checklist

1. Switch network:

   export HL_TESTNET=false
   

2. Deposit USDC to your HL sub-account via the Hyperliquid web UI

3. Verify balance:

   hl account --mainnet
   

4. Approve builder fee on mainnet (required again — separate from testnet approval):

   hl builder approve --mainnet
   

5. Test with a single strategy first:

   hl run engine_mm -i ETH-PERP --tick 15 --max-ticks 5 --mainnet
   

6. Verify: hl status

Network Differences

Common Mistakes

• Forgot to re-approve builder on mainnet → orders fail. Run hl builder approve --mainnet.
• No USDC deposited → orders fail with insufficient funds. Deposit first.
• Using testnet env with --mainnet flag → confusing. Set HL_TESTNET=false instead of mixing flags.
• Forgot --mainnet on a command → runs on testnet by accident (harmless but confusing).

Anti-Patterns

• Skipping builder fee approval → Every order fails silently. Always approve first.
• Going mainnet without testnet validation → Real money at risk with unverified setup.
• Running APEX before single-strategy test → APEX composes multiple systems — if any sub-component fails, debugging is harder.
• Ignoring password save → Keystore password cannot be recovered. Lose it = lose wallet access.
• Not setting HL_KEYSTORE_PASSWORD → CLI can't auto-unlock keystore. Every command will fail.

Complete Environment Variables

* Either keystore with HL_KEYSTORE_PASSWORD or HL_PRIVATE_KEY is required.

Composition

This skill is the entry point for all other skills. After completing onboarding:

• Trade: hl run <strategy> — see strategies with hl strategies
• APEX: hl apex run — multi-slot orchestrator
• REFLECT: hl reflect run — nightly performance review
• Radar: hl radar run — find trading opportunities
• Guard: hl guard run -i <instrument> — trailing stop protection