本页为简体中文译文。如有歧义，请以英文原文为准。 阅读英文版 →
跳转到主要内容

账户开通

本页介绍链上 Account 的生命周期、资金注入以及 API 钱包管理。合约地址见 Contracts，GET /exchange-info 会返回当前 Exchange、Factory 和入金路由合约的地址。

概览​

Hypercall 采用管理者（manager）加 API 钱包的模型：

  • Manager：创建并拥有 Account 的 EOA（通常是您的主钱包）。
  • Account：一个 BeaconProxy 合约，持有您在 HyperCore 上的余额和持仓，并执行已签名的指令。
  • API 钱包：由 manager 在 Account 上授权的 EOA，用于签署下单和撤单。

Account 由 Factory 创建。已签名的指令由 Hypercall 的排序器（sequencer）提交到 Exchange：您负责签名，Hypercall 负责提交。

Account 生命周期​

1. 查询已有 Account​

// Exchange
function getAccounts(address manager) external view returns (ManagedAccount[] memory);

struct ManagedAccount {
    address account;
    address manager;
    ApiWallet[] apiWallets; // { bytes32 name; address addr; }
}

2. 创建 Account​

// Factory
function createAccount(uint96 salt) external payable returns (address account);
function getCreationDeposit() external view returns (uint256); // in HYPE wei
function predictAccount(address manager, uint96 salt) external view returns (address account, bool exists);

要求：

  • msg.value >= getCreationDeposit()。Factory 以美元设定创建押金，并按 HyperCore 现货价格换算为 HYPE，向上取整。目前主网上为 $1.50。
  • 如果配置了创建过滤器，则该过滤器必须允许 msg.sender。

行为：

  • 使用 CREATE2，根据 manager 地址和 salt 部署 Account，因此可以通过 predictAccount 提前获知其地址。
  • 在 Exchange 中注册该 Account，并将 msg.sender 设为 manager。
  • 将全部 msg.value 以 HYPE 形式跨链转入该 Account 在 HyperCore 上的账户。价值至少 $1 的入金会在 HyperCore 上激活该 Account。
const factory = new ethers.Contract(FACTORY_ADDRESS, FACTORY_ABI, signer);
const salt = 0n;
const [predicted] = await factory.predictAccount(managerAddress, salt);
const value = await factory.getCreationDeposit();
await (await factory.createAccount(salt, { value })).wait();

3. Manager 变更​

合约不提供 manager 转让函数。只有在链上强制平仓拍卖结算时，manager 才会变更，而主网上并未配置拍卖人（auctioneer）。发生变更时，Exchange 会发出 AccountTransferred(account, oldManager, newManager)，Account 会发出 ManagerSet(oldManager, newManager)。

API 钱包管理​

API 钱包存储在 Account 上，以 bytes32 名称作为键。它们在 HypercallApiSign EIP-712 域中签署指令。详见 EIP-712 签名。

添加、替换或移除​

提交一条由 manager 在 HypercallManagerSign 域中签名的 hc_update_api_wallet 指令：

HCUpdateApiWallet(address account,uint64 nonce,UpdateApiWallet action)UpdateApiWallet(bytes32 name,address addr)
  • 使用新的 name 会添加一个钱包；使用已有的 name 会替换该名称下的钱包。
  • addr = 0x0 会移除 name 下的钱包。
  • API 钱包不能是 manager，也不能已经在该 Account 上处于激活状态。

将其发送到 POST /v1/actions/hc_update_api_wallet，请求中包含 account、nonce、action（{ "name": "0x...", "addr": "0x..." }）和 signature。POST /v1/actions/hc_update_api_wallet/typed-data 会返回需要签名的完整 typed data。轮询 GET /v1/directives/{directive_id} 以获取链上执行结果。Account 会发出 ApiWalletUpdated(name, addr)。

查询​

// Account
function getApiWallets() external view returns (ApiWallet[] memory);
function getApiWallet(bytes32 name) external view returns (address);
function isApiWalletActive(address addr) external view returns (bool);

资金与入金​

向 Hypercall 存入 USDC​

// Exchange
function depositUsdcFor(address account, uint256 amount) external;

depositUsdcFor 是在 HyperEVM 上直接为 Hypercall 现金入金的路径。它从 msg.sender 拉取原生 HyperEVM USDC 到 Exchange，再通过 Circle 的 CoreDepositWallet 存入 Exchange 在 HyperCore 上的余额。

谁可以调用：

  • 任意钱包、路由合约、solver 或 zap 合约。
  • 由 msg.sender 支付 USDC。
  • account 是需要入账的 Hypercall 账户或钱包。不要根据 msg.sender 推断入账账户。

要求：

  • account != address(0) 且 amount > 0
  • msg.sender 已授权 Exchange 使用 amount 数量的 USDC
event UsdcDeposit(
    address indexed account,
    address indexed from,
    address indexed token,
    uint256 amount,
    uint32 dstDex
);

只有在将该事件与观察到的 HyperCore 入金匹配之后，Hypercall 才会为账户入账现金。入账账户以 account 字段为准。

await usdc.approve(EXCHANGE_ADDRESS, amount);
await exchange.depositUsdcFor(accountAddress, amount);

Router 的 deposit(account, token, amount, isPerp) 是应用使用的通用辅助函数，适用于 USDC、现货代币和期权代币。

期权代币入金​

// Exchange
function depositOption(address account, address token, uint256 amount) external;
  • account 必须是已注册的 Hypercall Account。
  • token 必须是 Option Registry 中支持的期权。
  • 从 msg.sender 销毁 amount（需先授权 Exchange），并发出 Deposit(account, msg.sender, token, amount)，由引擎据此入账。

从 Account 转出​

// Account, manager only
function transferTo(address recipient, address token, uint256 amount) external;

将 Account 在 HyperEVM 上持有的原生 HYPE（token = 0x0）或 ERC20 转给 recipient。可用于完成从 HyperCore 到 HyperEVM 的转账，或清空 Account 余额。Account 处于强制平仓期间不可用。

永续合约的 Builder 授权​

// Account, manager only
function approveZeroFeeBuilder(address builder) external;

以 0% 的最高费率为该 Account 授权一个 Hyperliquid builder。每笔 Hypercall 永续合约订单都带有 Hypercall 的 builder code，因此在下第一笔永续合约订单之前，请使用 GET /exchange-info 返回的 hl_builder_address 调用一次该函数。应用会在 Enable trading 步骤中完成这一操作。

事件​

// Exchange
event AccountTransferred(address indexed account, address indexed oldManager, address indexed newManager);
event Deposit(address indexed account, address indexed from, address indexed token, uint256 amount);
event Withdraw(address indexed account, address indexed to, address indexed token, uint256 amount);
// Factory
event AccountCreated(address indexed account, address indexed manager);
// Account
event ApiWalletUpdated(bytes32 indexed name, address indexed addr);
event ManagerSet(address indexed oldManager, address indexed newManager);

错误​

  • Factory__CreationDepositNotMet(uint256 expected)：msg.value 低于创建押金
  • Factory__CreationNotAllowed()：被创建过滤器拦截
  • Exchange__AccountDoesNotExist(address account)：不是已注册的 Account
  • Exchange__TokenNotSupported(address token)：不是受支持的期权代币
  • Account__NotManager(address addr)：调用者或签名者不是 manager
  • Account__ApiWalletNotActive(address addr)：签名者不是已激活的 API 钱包
  • Account__ApiWalletAlreadyActive(address addr)：该 API 钱包已在 Account 上
  • Account__ApiWalletIsManager()：manager 不能作为自己的 API 钱包
  • Account__NonceAlreadyUsed(address signer, uint256 nonce)：nonce 重复使用
  • Account__LiquidationInProgress()：强制平仓期间该操作被禁止

安全注意事项​

  1. Manager 私钥：控制 API 钱包、资金转出和 builder 授权。请使用硬件钱包。
  2. API 钱包私钥：仅用于签署下单和撤单。每个系统使用独立的私钥，并定期轮换。
  3. Nonce：每个签名者拥有独立的 nonce 空间。请使用毫秒级时间戳，并在链下记录。
  4. 激活：Account 必须先在 HyperCore 上激活（至少存入价值 $1 的 HYPE），才能交易永续合约。
最后更新于