agent-onboarding

Agent Onboarding

Complete first-time setup for the YEX autonomous trading system on Hyperliquid. Follow every step in order. Do not skip steps. Verify each step before proceeding to the next.

Agent Mandate

You are onboarding onto the YEX trading system. Your goal is to reach a state where you can autonomously trade on Hyperliquid (testnet or mainnet). Every step has a verification command — if verification fails, fix the issue before continuing.

RULES:

• Follow steps sequentially — each depends on the previous
• NEVER skip builder fee approval — all orders will fail without it
• ALWAYS validate with a mock trade before going live
• NEVER start on mainnet without completing testnet validation first
• Save all credentials (passwords, addresses) — they cannot be recovered

---

Step 1: Environment Bootstrap

Install Python dependencies and verify the CLI works.

Option A — Shell script (recommended):

cd ~/agent-cli
bash scripts/bootstrap.sh

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