hyperliquid-run

Repo: ~/dev/hyperliquid (dev branch) State file: ~/agent-state/hyperliquid-sdk.md Private key: ~/.config/hyperliquid-agent/env Ruby: always use RBENV_VERSION=3.4.8

Step 1: Read state

Read ~/agent-state/hyperliquid-sdk.md in full. Note:

• Current SDK version
• Last run date and outcome
• Upstream reference SHAs (Python SDK, TS SDK, docs)
• All known gaps and their statuses (🔧 bugs, 🟡 queued, 🔴 needs_approval)
• Any approved architectural changes ready to implement
• Todos/housekeeping items

Step 2: Ensure on dev branch and up to date

bash
1cd ~/dev/hyperliquid
2git checkout dev
3git pull origin dev
4RBENV_VERSION=3.4.8 bundle install --quiet

Step 3: Scan upstream references (skip if SHA unchanged)

For each upstream source, fetch the current HEAD SHA via GitHub API:

bash
1curl -s "https://api.github.com/repos/hyperliquid-dex/hyperliquid-python-sdk/commits/master" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['sha'][:12], d['commit']['committer']['date'][:10])"
2curl -s "https://api.github.com/repos/nktkas/hyperliquid/commits/main" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['sha'][:12], d['commit']['committer']['date'][:10])"

Compare to the SHAs in the state file. For any source whose SHA has changed (or was never scanned):

• Python SDK: Extract method signatures only — do NOT fetch full files:

  bash
  1curl -s "https://raw.githubusercontent.com/hyperliquid-dex/hyperliquid-python-sdk/master/hyperliquid/info.py" | grep -E "^\s+def " | sed 's/^\s*//'
  2curl -s "https://raw.githubusercontent.com/hyperliquid-dex/hyperliquid-python-sdk/master/hyperliquid/exchange.py" | grep -E "^\s+def " | sed 's/^\s*//'

  Compare against Ruby SDK signatures:

  bash
  1grep -E "^\s+def " ~/dev/hyperliquid/lib/hyperliquid/info.rb
  2grep -E "^\s+def " ~/dev/hyperliquid/lib/hyperliquid/exchange.rb

  For any gap you plan to implement this run, fetch the full upstream method body to understand its parameters and behaviour.

• TS SDK (nktkas): The repo uses one file per method. List the method directories directly — no file fetching needed for the comparison pass:

  bash
  1curl -s "https://api.github.com/repos/nktkas/hyperliquid/contents/src/api/info/_methods" \
  2  | python3 -c "import sys,json; [print(f['name'].replace('.ts','')) for f in json.load(sys.stdin)]"
  3curl -s "https://api.github.com/repos/nktkas/hyperliquid/contents/src/api/exchange/_methods" \
  4  | python3 -c "import sys,json; [print(f['name'].replace('.ts','')) for f in json.load(sys.stdin)]"

  Compare the resulting method names against the Ruby SDK. For any gap you plan to implement, fetch the specific .ts file to understand parameters and return type.

• HL API docs: WebFetch the Hyperliquid GitBook docs for new endpoint types, new action types, new subscription channels.

For each gap found:

• If already in the state file, skip.
• If it's a new method/endpoint that fits the existing architecture (no new classes, no new deps), add it to Known Gaps as 🟡 queued.
• If it requires architectural changes (new signing scheme, new transport, new major dependency), add it as 🔴 needs_approval with a one-paragraph description of what's needed and why. Do NOT implement it — flag it and move on.

Update the upstream SHA and scan date in the state file for any source actually scanned.

Step 4: Define scope for this run

From the state file, select gaps to implement this session. Apply these constraints:

• Max 3 gaps per run (session time budget).
• Priority order: 🔧 bugs first → approved architectural changes → oldest-queued 🟡 gaps → housekeeping todos.
• Skip anything marked 🔴 needs_approval that is not yet approved.
• If there is nothing to implement, skip to Step 9 (update state + email).

Write a brief scope summary (1–3 bullet points) to refer back to during the run.

Step 5: Implement

For each gap in scope:

1. Read the relevant source files before editing. Understand the existing pattern.
2. Implement the method/feature in the appropriate file (lib/hyperliquid/info.rb, lib/hyperliquid/exchange.rb, lib/hyperliquid/ws/, etc.), following existing code style.
3. Write a unit test in spec/ mirroring the existing test structure (WebMock stubs for HTTP methods, no live calls in unit tests).
4. Run the single spec file to verify before moving on:

   bash
   1cd ~/dev/hyperliquid && RBENV_VERSION=3.4.8 bundle exec rspec spec/path/to/new_spec.rb

5. Mark the gap 🔵 in_progress in the state file, then ✅ done once the test passes.

Do not implement more than the defined scope even if time seems available — stay within the session budget.

Step 6: Run full test suite

bash
1cd ~/dev/hyperliquid
2RBENV_VERSION=3.4.8 bundle exec rake

Fix any failures before continuing. If a failure is unrelated to this run's changes, note it in the state file and email summary but do not block the commit.

Step 7: Run integration tests

Load the private key and run the automated integration suite:

bash
1cd ~/dev/hyperliquid
2source ~/.config/hyperliquid-agent/env
3RBENV_VERSION=3.4.8 HYPERLIQUID_PRIVATE_KEY=$HYPERLIQUID_PRIVATE_KEY ruby scripts/test_automated.rb

Before investigating any failures, cross-reference against the Known Pre-existing Failures section in the state file. If a failure matches a known pre-existing issue, note it in the email but do not spend tool calls re-investigating it. Only investigate genuinely new failures.

If a new failure is caused by this run's changes, fix before committing. If it's an unrelated flake, note it.

Step 8: Sync CLAUDE.md if needed

Before staging the commit, decide whether ~/dev/hyperliquid/CLAUDE.md needs updating. CLAUDE.md is the canonical source of truth for the repo and should stay current.

Update it whenever this run:

• Bumps the SDK version (the "currently vX.Y.Z" line).
• Adds a new pattern, transport, dependency, constant, or convention a future agent reading the repo cold would want to know (e.g. a new base URL, a new signing variant, a new test harness file).
• Changes how something documented in CLAUDE.md actually works (architecture, request flow, signing, numeric conversion, code style, CI matrix, release flow).
• Introduces a new gotcha worth preserving (the dump_status String-response guard is the canonical example).

Routine additions that fit cleanly into existing patterns (one more Info method, one more Exchange action that uses the existing signer) generally do not need a CLAUDE.md update. Skip it rather than churn the file.

If you do edit CLAUDE.md, include it in the same commit as the code change.

Step 9: Commit and push

bash
1cd ~/dev/hyperliquid
2git add lib/hyperliquid/info.rb spec/hyperliquid/info_spec.rb  # stage specific files (include CLAUDE.md if updated)
3git commit -m "feat: <concise description of what was implemented>
4
5Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
6git push origin dev

If nothing was implemented (no gaps or scope was zero), skip the commit.

Step 10: Update state file

Edit ~/agent-state/hyperliquid-sdk.md:

• Update Last run date and outcome.
• Update upstream SHA/scan dates for any sources scanned this run.
• Update gap statuses (🟡→✅, new gaps added, 🔧 bugs fixed, etc.).
• Append a row to the Run History table.

Step 11: Email summary

Send an email to carter2099@pm.me with subject Hyperliquid SDK run — <date>.

Use the send_digest.py script pattern:

bash
1python3 ~/scripts/send_digest.py \
2  --to carter2099@pm.me \
3  --subject "Hyperliquid SDK run — $(date +%Y-%m-%d)" \
4  --body "<html body>"

Email body should include:

• What was implemented this run (or "nothing new to implement" if scope was empty)
• New gaps discovered (if any), with a note if any need approval
• Test results (unit + integration pass/fail summary)
• Anything needing manual action (needs_approval items, test failures requiring investigation)
• Next run preview — what's queued for next time

Keep it concise. Carter reads these on mobile.

Step 12: Backup state file reminder

The state file is backed up by homelab-backup nightly. No action needed — just don't delete it.