接入前 vs 接入后

用户持有 TRON 上的 USDT，想给自己的 HyperLiquid 保证金账户充值。绿色圆点是用户的钱走的路线。

用户在钱包里看到的

1. 打开钱包里的 HyperLiquid 充值入口和现在一样的位置。
2. 选择手里的资产，输入金额TRX、ETH、SOL、USDT 等都可以，页面显示预计到账多少 USDC。
3. 点一次充值，在钱包里确认签名资产自动换成 USDC，送到他的 HyperLiquid 保证金账户；部分路线最后还要再签一次名（免手续费）。

先把几个词说清楚

HyperLiquid 保证金账户

用户在 HyperLiquid 上放交易本金的账户。往里充钱，就能开始交易。

USDC · Arbitrum

保证金账户只收 USDC（与美元 1:1 的数字货币），而且只从 Arbitrum 这条链收。

为什么需要这个 API

用户手里的往往不是 Arbitrum 上的 USDC。这个 API 负责把他手里的资产换好、送到，充进保证金账户。

它只做这一件事

接入步骤

1. 开通合作方账号联系商务，拿到沙箱 key（hk_test_…）和 secret。上线前提供后端出口 IP，换成正式 key（hk_live_…）。
2. 在你的服务端对接签名每个请求用 HMAC-SHA256 签名，secret 只放服务端，不进 App 或浏览器。接入指南里有四种语言的示例和测试向量。
3. 调用报价接口，显示预计到账资产列表用 GET /v1/assets 取，不要写死（各链原生币和代币会随流动性方更新）。询价时传入资产、数量、用户钱包地址和他的 HyperLiquid 地址，返回多条路线，已按用户到手最多排好序，附带手续费、用时和需要签几次名。
4. 用户确认，钱包逐步签名下单后得到 steps[]。每一步先取最新的待签名交易，交给用户的钱包签名并广播，再提交交易哈希。
5. 等回调，直到充进保证金账户订单状态变化时我们回调你的服务端（order.completed 等）。也可以查询订单，向用户展示进度。

// 0. 资产列表：来源资产、精度、最小金额（没有固定下限时为 null）、是否原生币
GET  /v1/assets

// 1. 报价：用户输入金额时调用（服务端，HMAC 签名）
POST /v1/quotes   { source: { asset: "tron:USDT", amount: "500000000", from_address: "T…" },
                    destination: { asset: "hyperliquid:USDC_PERP", address: "0x…" }, end_user: {…} }
// → routes[]（已排序）、recommended_route_id；报价 60 秒有效

// 2. 下单：用户点「一键充值」时调用（必带 Idempotency-Key）
POST /v1/orders   { quote_id, route_id, partner_order_id }
// → Order：steps[] 里是待签名的步骤（授权、兑换、存入…）

// 3. 每个步骤：取交易 → 用户钱包签名并广播 → 提交哈希
POST /v1/orders/{id}/steps/{step_id}/prepare
POST /v1/orders/{id}/steps/{step_id}/submit   { tx_hash }

// 4. 进度：以回调为主，查询为辅
webhook order.completed        GET /v1/orders/{id}
// → 等待签名 / 处理中 / 还差最后一步 / 已完成 / 已退款 …

文档与商务

系统结构

真实接口对接表

全部来自 HL Deposit API 的 OpenAPI 契约（JSON，HMAC 签名）。前端只和自己的后端说话，key id 与 secret 不出现在浏览器里。

订单状态怎样变成用户看得懂的话

状态值是开放枚举：遇到不认识的值，一律按「处理中」展示，不报错。

设计决定

上线前需要确认的事项

如何运行完整版

# Node 18 以上，没有 npm 依赖
cp .env.example .env        # 填入 HLD_BASE_URL、HLD_KEY_ID、HLD_SECRET，确认后设 KYC_ATTESTED=1
node server.js              # 打开 http://localhost:8787