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