Bắt đầu sử dụng

Trang này trình bày vòng đời của Account on-chain, cách nạp tiền và cách quản lý ví API. Các địa chỉ hợp đồng được liệt kê tại Contracts, và GET /exchange-info trả về địa chỉ hiện hành của Exchange, Factory và deposit router.

Tổng quan

Hypercall sử dụng mô hình gồm manager và ví API:

Manager: EOA tạo và sở hữu Account (thường là ví chính của bạn).
Account: một hợp đồng BeaconProxy nắm giữ số dư và vị thế HyperCore của bạn, đồng thời thực thi các directive đã ký.
Ví API: một EOA được manager ủy quyền trên Account để ký lệnh và lệnh hủy.

Account được tạo bởi Factory. Các directive đã ký được sequencer của Hypercall gửi tới Exchange. Bạn ký, Hypercall gửi giao dịch.

Vòng đời Account

1. Kiểm tra các Account hiện có

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

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

2. Tạo 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);

Yêu cầu:

msg.value >= getCreationDeposit(). Factory đặt khoản tiền nạp khi tạo tài khoản theo USD và quy đổi sang HYPE theo giá spot trên HyperCore, làm tròn lên. Trên mạng chính, khoản này hiện là $1.50.
Nếu có cấu hình bộ lọc tạo tài khoản, bộ lọc đó phải cho phép msg.sender.

Cách hoạt động:

Triển khai Account bằng CREATE2 từ địa chỉ manager và salt, vì vậy địa chỉ có thể biết trước thông qua predictAccount.
Đăng ký Account với Exchange và đặt msg.sender làm manager.
Chuyển toàn bộ msg.value sang Account trên HyperCore dưới dạng HYPE. Một khoản nạp trị giá tối thiểu $1 sẽ kích hoạt Account trên HyperCore.

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. Thay đổi manager

Không có hàm chuyển quyền manager. Manager chỉ có thể thay đổi khi một phiên đấu giá thanh lý on-chain được hoàn tất, và hiện không có auctioneer nào được cấu hình trên mạng chính. Khi có thay đổi, Exchange phát ra AccountTransferred(account, oldManager, newManager) và Account phát ra ManagerSet(oldManager, newManager).

Quản lý ví API

Ví API được lưu trên Account, với khóa là một tên kiểu bytes32. Các ví này ký directive trong domain EIP-712 HypercallApiSign. Xem Ký EIP-712.

Thêm, thay thế hoặc xóa

Gửi một directive hc_update_api_wallet do manager ký trong domain HypercallManagerSign:

HCUpdateApiWallet(address account,uint64 nonce,UpdateApiWallet action)UpdateApiWallet(bytes32 name,address addr)

Một name mới sẽ thêm ví. Một name đã tồn tại sẽ thay thế ví tương ứng.
addr = 0x0 sẽ xóa ví thuộc name.
Ví API không được trùng với manager và không được đang hoạt động sẵn trên Account.

Gửi tới POST /v1/actions/hc_update_api_wallet với account, nonce, action ({ "name": "0x...", "addr": "0x..." }) và signature. POST /v1/actions/hc_update_api_wallet/typed-data trả về chính xác dữ liệu typed data cần ký. Truy vấn định kỳ GET /v1/directives/{directive_id} để lấy kết quả on-chain. Account sẽ phát ra ApiWalletUpdated(name, addr).

Truy vấn

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

Nạp tiền

Nạp USDC vào Hypercall

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

depositUsdcFor là đường nạp tiền trực tiếp trên HyperEVM để cấp tiền mặt cho Hypercall. Hàm này kéo USDC gốc trên HyperEVM từ msg.sender vào Exchange, sau đó nạp vào số dư HyperCore của Exchange thông qua CoreDepositWallet của Circle.

Ai có thể gọi:

Bất kỳ ví, router, solver hoặc hợp đồng zap nào.
msg.sender là bên trả USDC.
account là tài khoản hoặc ví Hypercall được ghi có. Không suy ra tài khoản được ghi có từ msg.sender.

Yêu cầu:

account != address(0) và amount > 0
msg.sender đã approve cho Exchange số USDC bằng amount

event UsdcDeposit(
    address indexed account,
    address indexed from,
    address indexed token,
    uint256 amount,
    uint32 dstDex
);

Hypercall chỉ ghi có tiền mặt sau khi đối chiếu sự kiện này với khoản nạp quan sát được trên HyperCore. Tài khoản được ghi có là trường account.

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

Hàm deposit(account, token, amount, isPerp) của Router là hàm hỗ trợ tổng quát mà ứng dụng dùng cho USDC, token spot và token quyền chọn.

Nạp token quyền chọn

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

account phải là một Account Hypercall đã đăng ký.
token phải là một quyền chọn được hỗ trợ trong Option Registry.
Đốt amount từ msg.sender (cần approve cho Exchange trước) và phát ra Deposit(account, msg.sender, token, amount), sau đó engine sẽ ghi có.

Chuyển tiền ra khỏi Account

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

Chuyển HYPE gốc (token = 0x0) hoặc một token ERC20 mà Account đang nắm giữ trên HyperEVM tới recipient. Hãy dùng hàm này để hoàn tất việc chuyển từ HyperCore sang HyperEVM hoặc để rút toàn bộ tài sản khỏi Account. Không khả dụng khi Account đang bị thanh lý.

Phê duyệt builder cho perp

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

Phê duyệt một builder Hyperliquid cho Account với mức phí tối đa 0%. Mọi lệnh perp của Hypercall đều mang builder code của Hypercall, vì vậy hãy gọi hàm này một lần với hl_builder_address lấy từ GET /exchange-info trước lệnh perp đầu tiên. Ứng dụng thực hiện việc này ở bước Enable trading.

Sự kiện

// 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);

Lỗi

Factory__CreationDepositNotMet(uint256 expected): msg.value thấp hơn khoản nạp khi tạo tài khoản
Factory__CreationNotAllowed(): bị bộ lọc tạo tài khoản chặn
Exchange__AccountDoesNotExist(address account): không phải Account đã đăng ký
Exchange__TokenNotSupported(address token): không phải token quyền chọn được hỗ trợ
Account__NotManager(address addr): bên gọi hoặc bên ký không phải manager
Account__ApiWalletNotActive(address addr): bên ký không phải ví API đang hoạt động
Account__ApiWalletAlreadyActive(address addr): ví API đã có trên Account
Account__ApiWalletIsManager(): manager không thể làm ví API của chính mình
Account__NonceAlreadyUsed(address signer, uint256 nonce): nonce bị dùng lại
Account__LiquidationInProgress(): thao tác bị chặn trong quá trình thanh lý

Lưu ý bảo mật

Khóa manager: kiểm soát ví API, việc chuyển tiền ra và phê duyệt builder. Hãy sử dụng ví phần cứng.
Khóa ví API: chỉ ký lệnh và lệnh hủy. Hãy dùng khóa riêng cho từng hệ thống và xoay vòng khóa định kỳ.
Nonce: mỗi bên ký có không gian nonce riêng. Hãy dùng timestamp tính bằng mili giây và theo dõi nonce ở phía off-chain.
Kích hoạt: Account phải được kích hoạt trên HyperCore (đã nạp ít nhất $1 HYPE) trước khi có thể giao dịch perp.

Tổng quan​

Vòng đời Account​

1. Kiểm tra các Account hiện có​

2. Tạo Account​

3. Thay đổi manager​

Quản lý ví API​

Thêm, thay thế hoặc xóa​

Truy vấn​

Nạp tiền​

Nạp USDC vào Hypercall​

Nạp token quyền chọn​

Chuyển tiền ra khỏi Account​

Phê duyệt builder cho perp​

Sự kiện​

Lỗi​

Lưu ý bảo mật​