fix(hyperliquid): use Withdrawable field as primary source for available balance

[zhouyongyou]

Problem

Users with USDC in Hyperliquid futures accounts were seeing false "insufficient balance" errors when attempting to open positions, despite having sufficient funds.

Root Cause Analysis

Initial Understanding (Incorrect)

We first thought the issue was simply negative balance calculation:

• availableBalance = accountValue - totalMarginUsed
• Could result in negative values

Deeper Investigation (Correct)

The real problem is more fundamental:

• Hyperliquid's TotalMarginUsed calculation differs from Binance
• May include maintenance margin requirements, not just initial margin
• Simply preventing negative values (setting to 0) is insufficient

Example Failure Scenario

• User has 1000 USDC
• accountValue = 1000, totalMarginUsed = 1050
• V1 fix: availableBalance = 0 (prevented negative)
• User tries to open 100 USDT position
• Result: Still fails with "insufficient balance" ❌

Correct Solution

Use Hyperliquid API's native Withdrawable field:

• This is the official withdrawable balance calculated by Hyperliquid
• Already accounts for all position risks and margin requirements
• Accurately reflects user's true available funds

Implementation Strategy

1. Primary: Use accountState.Withdrawable field (real available balance)
2. Fallback: If Withdrawable unavailable, use calculated value (with negative protection)
3. Logging: Clear indication of which data source is used

Technical Details

According to Hyperliquid API docs and CCXT discussions (#23997, #26671):

• withdrawable field is at top level of clearinghouseState response
• Recommended approach: free = withdrawable
• Updates more quickly than calculated values
• Represents actual withdrawable amount

Impact

• ✅ Fixes false "no money" errors for Hyperliquid users
• ✅ Uses official API field instead of custom calculation
• ✅ Maintains backward compatibility with fallback logic
• ✅ Does not affect Binance or Aster implementations

📝 Description | 描述

English:
Fixes false "insufficient balance" errors for Hyperliquid users by using the API's native Withdrawable field instead of custom calculation. The previous approach of calculating availableBalance = accountValue - totalMarginUsed was fundamentally flawed because Hyperliquid's margin calculation differs from Binance.

中文：
通过使用Hyperliquid API原生的Withdrawable字段而非自定义计算，修复了Hyperliquid用户的虚假"余额不足"错误。之前的availableBalance = accountValue - totalMarginUsed计算方法存在根本性缺陷，因为Hyperliquid的保证金计算方式与币安不同。

---

🎯 Type of Change | 变更类型

• 🐛 Bug fix | 修复 Bug（不影响现有功能的修复）
• ✨ New feature | 新功能（不影响现有功能的新增）
• 💥 Breaking change | 破坏性变更（会导致现有功能无法正常工作的修复或功能）
• 📝 Documentation update | 文档更新
• ♻️ Refactoring | 重构（无功能变更）
• ⚡ Performance improvement | 性能优化

---

🔗 Related Issues | 相关 Issue

User Report:

"hy合约账户有usdc为什么一直提示没钱"
(Hyperliquid futures account has USDC but keeps showing "no money")

Problem Analysis:
Users with sufficient USDC balance in Hyperliquid were unable to open positions due to false "insufficient balance" errors.

---

🔍 Root Cause Analysis | 根因分析

Initial Understanding (Incorrect) ❌

Symptom:

availableBalance = accountValue - totalMarginUsed
// Could result in negative values

Initial Fix (V1):

availableBalance = max(0, accountValue - totalMarginUsed)

Problem with V1:
While it prevented negative values, it didn't solve the underlying issue.

Example Failure Scenario:

User has: 1000 USDC
accountValue: 1000
totalMarginUsed: 1050 (Hyperliquid calculation includes more factors)
V1 Result: availableBalance = 0

User tries to open 100 USDT position
100 > 0 → Still fails! ❌

Correct Understanding ✅

Root Cause:
Hyperliquid's TotalMarginUsed calculation differs fundamentally from Binance:

• May include maintenance margin requirements
• Not just simple initial margin = position_value / leverage
• Custom calculation formula is unreliable

Correct Solution:
Use Hyperliquid API's native Withdrawable field:

• Official withdrawable balance calculated by Hyperliquid
• Already accounts for all position risks
• Updates quickly and accurately reflects available funds

---

📋 Changes Made | 具体变更

Core Logic Change

Before:

result["availableBalance"] = accountValue - totalMarginUsed

After:

// ⚠️ 优先使用Withdrawable字段（Hyperliquid API返回的真实可用余额）
availableBalance := 0.0
if accountState.Withdrawable != "" {
    withdrawable, err := strconv.ParseFloat(accountState.Withdrawable, 64)
    if err == nil {
        availableBalance = withdrawable
        log.Printf("✓ 使用Hyperliquid API的Withdrawable字段: %.2f USDT", availableBalance)
    }
}

// 后备方案：如果Withdrawable不可用，使用计算值（确保不为负数）
if availableBalance == 0 && accountState.Withdrawable == "" {
    availableBalance = accountValue - totalMarginUsed
    if availableBalance < 0 {
        log.Printf("⚠️ [Hyperliquid] 计算的可用余额为负，已调整为0")
        availableBalance = 0
    }
}

result["availableBalance"] = availableBalance

Strategy

1. Primary: Use accountState.Withdrawable field (official API value)
2. Fallback: If Withdrawable unavailable, use calculated value with negative protection
3. Logging: Clear indication of which data source is used

---

📊 Comparison Table | 对比表

Scenario	accountValue	totalMarginUsed	Withdrawable	V1 Result	V2 Result
No position	1000	0	1000	✅ 1000	✅ 1000
Light position	1000	200	800	✅ 800	✅ 800
Heavy position	1000	950	50	✅ 50	✅ 50
Full position	1000	1050	5	❌ 0	✅ 5

Key Difference: V2 correctly shows 5 USDT available in the full position scenario, allowing small trades.

---

🧪 Testing | 测试

Manual Testing | 手动测试

• Tested locally | 本地测试通过
• Compiled successfully | 编译成功
• Verified SDK supports Withdrawable field | 验证SDK支持Withdrawable字段
• Tested with real Hyperliquid account (pending user feedback) | 使用真实Hyperliquid账户测试（等待用户反馈）

Test Environment | 测试环境

• OS | 操作系统: macOS
• Go Version | Go 版本: 1.21+
• SDK: github.com/sonirico/go-hyperliquid v0.17.0

Expected Log Output | 预期日志输出

Success:

✓ 使用Hyperliquid API的Withdrawable字段: 1000.50 USDT
✓ Hyperliquid 账户: 总净值=1000.50, 可用=1000.50, 保证金占用=0.00

Fallback (if Withdrawable unavailable):

⚠️ [Hyperliquid] 计算的可用余额为负 (1000.00 - 1050.00 = -50.00)，已调整为0。

---

📚 Technical References | 技术参考

Hyperliquid API Documentation

• clearinghouseState endpoint: Returns withdrawable at top level
• Field represents actual withdrawable balance
• Updates more quickly than calculated values

Community Discussions

• CCXT issue #23997: Hyperliquid balance calculation issues
• CCXT issue #26671: FetchBalance returns incorrect values
• Recommended approach: free = withdrawable

SDK Verification

// github.com/sonirico/go-hyperliquid v0.17.0
type UserState struct {
    Withdrawable string `json:"withdrawable"` // ✅ Field exists
    MarginSummary CrossMarginSummary
    // ...
}

---

✅ Checklist | 检查清单

Code Quality | 代码质量

• My code follows the project's code style | 我的代码遵循项目代码风格
• I have performed a self-review of my code | 我已进行代码自查
• I have commented my code, particularly in hard-to-understand areas | 我已添加代码注释
• My changes generate no new warnings or errors | 我的变更没有产生新的警告或错误
• Code compiles successfully | 代码编译成功

Testing | 测试

• Code compiles and passes basic checks | 代码编译通过基本检查
• I have tested the logic with different scenarios | 我已测试不同场景的逻辑
• Real user testing completed (pending) | 真实用户测试完成（待完成）

Documentation | 文档

• I have updated the documentation accordingly | 我已相应更新文档
• I have added inline code comments where necessary | 我已在必要处添加代码注释
• Commit messages are clear and descriptive | 提交信息清晰明确

---

🔒 Security Considerations | 安全考虑

• No API keys or secrets are hardcoded | 没有硬编码 API 密钥
• No SQL injection vulnerabilities introduced | 未引入 SQL 注入漏洞
• Authentication/authorization properly handled | 认证/授权已正确处理
• Uses official API field instead of custom calculation | 使用官方API字段而非自定义计算

---

⚡ Performance Impact | 性能影响

• Performance unchanged | 性能无变化

Analysis:

• No additional API calls (uses existing response field)
• Simpler logic (direct field access vs calculation)
• Negligible performance difference

---

💥 Breaking Changes | 破坏性变更

No breaking changes

• Only affects internal balance calculation for Hyperliquid
• Binance and Aster implementations unchanged
• Backward compatible with fallback logic

---

📋 Files Changed | 变更文件

Modified:

• trader/hyperliquid_trader.go (+23 lines, -2 lines)

Total: ~25 lines changed

---

🎯 Review Focus Areas | 审查重点

Please pay special attention to:
请特别注意：

• Logic changes | 逻辑变更

  • Use of accountState.Withdrawable field
  • Fallback logic when Withdrawable is unavailable
  • Negative value protection in fallback path

• Error handling | 错误处理

  • ParseFloat error handling
  • Empty string checking
  • Logging for debugging

• Edge cases | 边界情况

  • Withdrawable field empty
  • Withdrawable field parsing fails
  • accountValue < totalMarginUsed

---

🌐 Additional Notes | 补充说明

Why This Approach is Correct

Hyperliquid API Design Philosophy:
Hyperliquid provides the withdrawable field specifically to avoid the complexity of manual calculation. This field:

• Accounts for maintenance margin
• Considers liquidation risks
• Updates in real-time with position changes
• Is the source of truth for available balance

Comparison with Binance:

• Binance: Simple formula works (initial margin = position_value / leverage)
• Hyperliquid: Complex margin system requires using official field

Future Improvements

If users report issues, we can:

1. Log the complete MarginSummary structure for debugging
2. Compare Withdrawable vs calculated values
3. Add metrics to track discrepancies
4. Further optimize the fallback logic

---

🤔 Questions for Reviewers | 审查者问题

1. Should we add a warning if Withdrawable field is empty? (Currently falls back silently)
2. Should we log the discrepancy between Withdrawable and calculated value for debugging?
3. Should we add unit tests for the parsing logic?

---

By submitting this PR, I confirm that:
提交此 PR，我确认：

• I have read the Contributing Guidelines | 我已阅读贡献指南
• I agree to the Code of Conduct | 我同意行为准则
• My contribution is licensed under the AGPL-3.0 License | 我的贡献遵循 AGPL-3.0 许可证
• I understand this is a voluntary contribution | 我理解这是自愿贡献
• I have the right to submit this code | 我有权提交此代码

[github-actions]

🤖 Advisory Check Results

These are advisory checks to help improve code quality. They won't block your PR from being merged.

📋 PR Information

Title Format: ✅ Good - Follows Conventional Commits
PR Size: 🟢 Small (27 lines: +25 -2)

🔧 Backend Checks

Go Formatting: ⚠️ Needs formatting

Files needing formatting

api/server.go
config/database.go
main.go
manager/trader_manager.go

Go Vet: ✅ Good
Tests: ✅ Passed

Fix locally:

go fmt ./...      # Format code
go vet ./...      # Check for issues
go test ./...     # Run tests

⚛️ Frontend Checks

Build & Type Check: ✅ Success

Fix locally:

cd web
npm run build  # Test build (includes type checking)

---

📖 Resources

• Contributing Guidelines
• Migration Guide

Questions? Feel free to ask in the comments! 🙏

---

These checks are advisory and won't block your PR from being merged. This comment is automatically generated from pr-checks-run.yml.

[hzb1115]

Duplicated