任意资产，一键充进 
HyperLiquid
任意链资产付款，自动换成 USDC，直达你的 HyperLiquid 保证金账户。
合作 API
任意币种，一步充值 Hyperliquid 合约账户
对接 anyin 充值接口（/v1），即可在钱包内以任意资产为 HyperLiquid 保证金账户入金。合作方仅需调用报价、下单与订单查询。
接入前 vs 接入后
用户持有 TRX，想给自己的 HyperLiquid 保证金账户充值。绿色圆点是用户的钱走的路线。
用户在钱包里看到的
- 打开钱包里的 HyperLiquid 充值入口和现在一样的位置。
- 选择手里的资产，输入金额TRX、BTC、ETH、USDT 等都可以，页面显示预计到账多少 USDC。
- 点一次充值，在钱包里确认付款资产自动换成 USDC，送到他的 HyperLiquid 保证金账户。
先把几个词说清楚
- HyperLiquid 保证金账户
- 用户在 HyperLiquid 上放交易本金的账户。往里充钱，就能开始交易。
- USDC · Arbitrum
- 保证金账户只收 USDC（与美元 1:1 的数字货币），而且只从 Arbitrum 这条链收。
- 为什么需要这个 API
- 用户手里的往往不是 Arbitrum 上的 USDC。这个 API 负责把他手里的资产换好、送到，充进保证金账户。
它只做这一件事
做：把资产充进 HyperLiquid 保证金账户
- 输入是用户手里的任意资产
- 输出只有一种：他保证金账户里的 USDC
- 用户全程不离开你的钱包
不做：其他用途
- 不是通用的币币兑换，不能换成别的币
- 不把用户引到外部页面或其他 App
- 不替代你钱包现有的 HyperLiquid 对接
接入后，钱包里这些都不需要改：
合约下单持仓与平仓提现账户体系与登录原有 HyperLiquid 接口调用USDC 直接充值
接入步骤
- 申请 API Key向运营申请合作方 API Key。除健康检查外，请求头须携带 X-Api-Key，用于身份识别与结算对账。
- 在 HyperLiquid 充值入口增加「其他资产」保留原有 USDC 充值。用户选择其他资产时，由 anyin Deposit API 处理。
- 调用报价接口，展示预计入账传入 coinCode 与数量，返回预计入账 USDC、手续费及可充值范围。
- 用户确认后完成付款调用下单接口获取 depositAddress，由钱包完成签名付款，并提交交易哈希。
- 查询订单，直至入账完成使用 orderId 与 payerAddress 轮询订单状态，直至 USDC 入账至 HyperLiquid 保证金账户。
请求示例 Base URL：https://hl-test.mlion.ai
# 除健康检查外，所有请求均须携带以下请求头 X-Api-Key: <your_key> Content-Type: application/json # 1. 查询可付款资产 GET /v1/assets # 2. 获取报价，用于展示预计入账金额 POST /v1/deposit/quote { "coinCode": "TRX", "amount": "500" } # 展示 estReceiveUsdc，并校验 depositMin / depositMax。若 problems 非空，应提示用户且不得下单 # 3. 创建订单并获取付款地址 POST /v1/deposit/order { "coinCode": "TRX", "amount": "500", "hlAddress": "0x…", "payerAddress": "T…", "addressConfirmed": true } # 请用户按 depositAddress 及订单金额完成付款。若返回 depositMemo，转账时必须填写 # 4. 转账成功后提交交易哈希 POST /v1/deposit/order/{orderId}/txid { "txid": "0x…" } # 5. 建议每 6 秒查询一次，直至入账完成 GET /v1/deposit/order/{orderId}?payerAddress=T… # stage 含义见下方「接口说明」
接口说明
以下为合作方需对接的全部接口。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/health | 健康检查。用于确认服务可用性，调用时无需 API Key。 |
| GET | /v1/assets | 查询可付款资产。返回可用于付款的币种，包含币种代码、所在链及合约地址，供充值页展示资产列表。 |
| POST | /v1/deposit/quote | 获取报价。建议在用户输入或变更金额时调用。请求传入币种代码与数量，返回预计入账 USDC、手续费及该币种的充值上下限。若 problems 非空，应向用户展示 message，且不得创建订单。 |
| POST | /v1/deposit/order | 创建订单。建议在用户确认充值时调用。返回订单号与付款地址。用户须按该地址及订单金额，支付其所选币种。 |
| POST | /v1/deposit/order/{orderId}/txid | 提交付款哈希。钱包转账成功后调用，用于提交链上交易哈希，以便确认付款。 |
| GET | /v1/deposit/order/{orderId}?payerAddress= | 查询订单。建议付款后每 6 秒调用一次。使用订单号与付款钱包地址查询进度，直至入账完成，或订单进入退款、超时等终态。 |
| GET | /v1/deposit/orders?payerAddress=&pageNo= | 查询充值记录。按付款钱包地址分页返回历史订单，pageNo 从 1 起。 |
主要字段
- coinCode
- 付款币种代码，取自资产列表。报价与下单时须原样传入。
- amount
- 付款数量，字符串类型，例如 "500"。
- hlAddress
- 用户 HyperLiquid 地址，须为 0x 开头的 42 位地址。USDC 将入账至该地址对应的保证金账户。
- payerAddress
- 付款钱包地址。退款将退回该地址。查询单笔订单及历史记录时，须使用同一地址。
- addressConfirmed
- 须传 true，表示用户已确认 HyperLiquid 地址。未传 true 时，下单请求将被拒绝。
- depositAddress
- 下单成功后返回的收款地址。用户仅可向该地址转入与订单一致的币种及数量。币种或网络错误将导致资产无法找回。
- depositMemo
- 部分币种转账须填写备注。若返回该字段，转账时必须填写，遗漏可能导致资产无法找回。
- estReceiveUsdc
- 预计入账的 USDC 数量，建议展示于金额旁。
订单状态 stage
- awaiting_payment
- 订单已创建，等待用户完成付款。
- swapping
- 已收到付款，正在兑换为 USDC。
- delivering
- USDC 正在发往用户地址。
- delivered
- USDC 已入账至 HyperLiquid 保证金账户，可停止轮询。
- refunding
- 兑换未成功，原币正在退回付款地址。
- refunded
- 原币已退回付款地址。退款原因见 refundReason，可向用户展示。
- expired
- 超时未收到付款，订单已关闭。
- kyc
- 该金额须先完成身份认证。若返回 kycUrl，应引导用户前往。
- attention
- 订单正在人工处理。请引导用户联系客服并提供订单号。
- 鉴权
- 除健康检查外，请求头须携带 X-Api-Key。API Key 置于浏览器端存在泄露风险，建议由合作方服务端转发请求。如需由前端直接调用，请另行配置允许的来源（CORS）。
- 响应格式
- 成功时返回 { "ok": true, "data": … }，业务数据位于 data。失败时返回 { "ok": false, "code": "…", "message": "…" }。请以 code 判断错误类型，message 可直接向用户展示。常见错误码：unauthorized（API Key 缺失或无效）、rate_limited（请求过于频繁）、below_hl_min（预计入账低于 HyperLiquid 最低入账金额）。
- 轮询
- 创建订单后，建议每 6 秒查询一次。payerAddress 须与下单时的付款钱包地址一致，否则无法查询到该订单。
文档与商务
商务合作
API Key 申请、费率及结算方式。
请联系运营申请 API Key
整体架构与设计说明
一次付款，钱走过的四段路
anyin 把三件事串起来：OmniBridge 负责跨链兑换，Arbitrum 承接 USDC，Hyperliquid 官方桥合约负责入账。这一页说明每一段由谁完成、用的是哪个真实接口，以及上线前还需确认的事项。
系统结构
真实接口对接表
全部来自 OmniBridge 文档（API 根地址 https://api.omnibridge.pro，POST + JSON）。前端只和自己的后端说话，渠道号不出现在浏览器里。
| 用户看到的 | anyin 后端 | OmniBridge 接口 | 要点 |
|---|---|---|---|
| 币种列表、搜索 | GET /api/coins | /api/v1/queryCoinList | 只取支持兑换的币；按合约地址找出 Arbitrum 原生 USDC 作为固定目标，排除不支持兑换成它的币 |
| 预计到账、手续费 | POST /api/quote | /api/v1/getBaseInfo | 按文档公式：(数量 − 数量 × 费率) × 汇率 − 目标链网络费 |
| 一键充值 | POST /api/order | /api/v2/accountExchange | 下单前后端再报价一次并校验 ≥ 5 USDC；destinationAddr = 用户 HL 地址；返回 platformAddr |
| 付款完成 | POST /api/order/txid | /api/v2/modifyTxId | 钱包付款后自动提交哈希；手动转账可选填 |
| 进度条 | POST /api/order/state | /api/v2/queryOrderState | 每 6 秒轮询；detailState 映射成四步进度 |
| 充值记录 | POST /api/orders | /api/v2/queryAllTrade | 按本机设备号 equipmentNo 查询 |
| 进入保证金账户 | POST /api/hl/permit-deposit | Hyperliquid Bridge2（非 OmniBridge） | 用户签 USDC permit，后端校验签名后调用 batchedDepositWithPermit，并检查 FailedPermitDeposit 事件 |
订单状态怎样变成用户看得懂的四步
| OmniBridge detailState | 页面上的说法 | 进度位置 |
|---|---|---|
wait_deposit_send | 等待您付款 | ① 付款 |
wait_exchange_push · wait_exchange_return | 正在换成 USDC | ② 兑换 |
wait_receive_send · wait_receive_confirm | USDC 正在发往您的地址 | ③ 到账 Arbitrum |
receive_complete | USDC 已到账，签名后进入保证金账户 | ④ 入账 HyperLiquid |
wait_refund_* · refund_complete | 兑换未成功，原币退回，附退款原因 | 退款分支 |
timeout · WAIT_KYC · ERROR | 订单超时 / 需要身份认证 / 处理中请联系客服 | 异常分支 |
设计决定
目标固定，不给选择器到账框只展示「HyperLiquid 保证金账户 · USDC · Arbitrum」，带锁标记。系统按合约地址锁定原生 USDC，不会误选 USDC.e。
一个主按钮「一键充值」承担连接钱包、下单、发起付款三件事。按钮上方一行字说明当前还差什么。
付款方式由币种决定EVM 币走钱包签名，TRX/TRC20 走 TronLink，其他链展示地址和金额。用户在选币时就能看到「钱包直付」或「转账付款」。
地址确认冷静而明确EVM 自动带入地址并要求勾选确认；非 EVM 手动填写，地址分段回显，首尾高亮，便于逐段核对。
不编造数字费率、汇率、网络费全部来自实时报价；预计用时引用 OmniBridge 文档并注明来源；没有数据时显示「—」。
动效只说明流向报价时竖线上的圆点下落表示钱在路上；进度页当前步骤有呼吸圈。系统开启「减少动态效果」时全部关闭。
上线前需要确认的事项
关键
最后一步需要用户签一次名OmniBridge 只能把 USDC 打到一个地址。直接打给 Hyperliquid 桥合约会记到 OmniBridge 的发款地址名下，资金会错账，所以必须先打到用户自己的地址，再由用户签 permit 授权存入（免 gas，由我方中继付 gas）。若要做到完全无签名，需要 OmniBridge 支持「代用户存入 Hyperliquid」的发款方式，建议商务优先确认。
关键
渠道号 sourceFlag所有接口都要求渠道号，需与 OmniBridge 商务确认后填入后端配置。
重要
地区限制OmniBridge 文档说明其 API 在美国、中国大陆、伊朗、俄罗斯等地区不可用。产品上线地区与准入策略需法务确认。
重要
中继钱包自动入账需要一个持有少量 Arbitrum ETH 的中继地址付 gas。未配置时，页面改为让用户自己从钱包存入（需少量 ETH）。
重要
5 USDC 最低入账Hyperliquid 不入账低于 5 USDC 的存款。下单前按「最少到账」校验，不足时直接拦截。
待补
文档未覆盖的部分付款地址的有效期、需要 memo 的币（如 XRP、XLM）的付款地址格式、币种图标的完整地址。当前实现：地址中带 # 时拆出 memo 单独展示；图标加载失败时用首字母代替。
如何运行完整版
# Node 18 以上 cp .env.example .env # 填入 SOURCE_FLAG；可选 ARB_RPC_URL、RELAYER_PRIVATE_KEY npm install # 仅自动入账中继需要 ethers node server.js # 打开 http://localhost:8787