이 페이지는 자동 번역되었습니다. 영어 원문이 정본입니다. 영어로 읽기 →
메인 콘텐츠로 건너뛰기

온보딩

이 페이지에서는 온체인 Account의 생명주기, 자금 입금, API 지갑 관리를 다룹니다. 주소는 Contracts에서 확인할 수 있으며, GET /exchange-info는 현재 운영 중인 Exchange, Factory, 입금 라우터 주소를 반환합니다.

개요​

Hypercall은 매니저와 API 지갑 모델을 사용합니다.

  • 매니저(Manager): Account를 생성하고 소유하는 EOA입니다(보통 메인 지갑).
  • Account: HyperCore 잔고와 포지션을 보유하고 서명된 디렉티브를 실행하는 BeaconProxy 컨트랙트입니다.
  • API 지갑: 매니저가 Account에 승인하여 주문과 취소에 서명할 수 있게 한 EOA입니다.

Account는 Factory가 생성합니다. 서명된 디렉티브는 Hypercall의 시퀀서가 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는 생성 예치금을 USD로 설정하고 HyperCore 현물 가격으로 HYPE로 환산하며, 올림 처리합니다. 메인넷에서는 현재 $1.50입니다.
  • 생성 필터가 설정된 경우, 해당 필터가 msg.sender를 허용해야 합니다.

동작:

  • 매니저 주소와 salt로 CREATE2를 사용해 Account를 배포하므로, predictAccount를 통해 주소를 미리 알 수 있습니다.
  • Account를 Exchange에 등록하고 msg.sender를 매니저로 설정합니다.
  • msg.value 전액을 HYPE로 HyperCore상의 Account에 브리지합니다. $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. 매니저 변경​

매니저 이전 함수는 없습니다. 매니저는 온체인 청산 경매가 종료될 때만 변경될 수 있으며, 메인넷에는 경매인(auctioneer)이 설정되어 있지 않습니다. 변경 시 Exchange는 AccountTransferred(account, oldManager, newManager)를, Account는 ManagerSet(oldManager, newManager)를 발생시킵니다.

API 지갑 관리​

API 지갑은 bytes32 이름을 키로 Account에 저장됩니다. API 지갑은 HypercallApiSign EIP-712 도메인에서 디렉티브에 서명합니다. EIP-712 서명을 참고하십시오.

추가, 교체, 제거​

매니저가 HypercallManagerSign 도메인에서 서명한 hc_update_api_wallet 디렉티브를 제출합니다.

HCUpdateApiWallet(address account,uint64 nonce,UpdateApiWallet action)UpdateApiWallet(bytes32 name,address addr)
  • 새로운 name이면 지갑이 추가됩니다. 기존 name이면 해당 지갑이 교체됩니다.
  • addr = 0x0이면 name에 해당하는 지갑이 제거됩니다.
  • API 지갑은 매니저와 같을 수 없으며, 이미 Account에서 활성 상태인 지갑일 수 없습니다.

account, nonce, action({ "name": "0x...", "addr": "0x..." }), signature를 포함해 POST /v1/actions/hc_update_api_wallet으로 전송합니다. 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는 Hypercall 현금을 HyperEVM에서 직접 입금하는 경로입니다. msg.sender로부터 HyperEVM 네이티브 USDC를 Exchange로 가져온 뒤, Circle의 CoreDepositWallet을 통해 Exchange의 HyperCore 잔고에 입금합니다.

호출 가능 주체:

  • 모든 지갑, 라우터, 솔버, zap 컨트랙트.
  • USDC는 msg.sender가 지불합니다.
  • account는 입금이 반영될 Hypercall 계정 또는 지갑입니다. 입금 대상 계정을 msg.sender로부터 추론하지 마십시오.

요건:

  • account != address(0)이고 amount > 0
  • msg.sender가 Exchange에 amount USDC만큼 승인(approve)해 두어야 함
event UsdcDeposit(
    address indexed account,
    address indexed from,
    address indexed token,
    uint256 amount,
    uint32 dstDex
);

Hypercall은 이 이벤트를 관측된 HyperCore 입금과 대조한 후에만 현금을 반영합니다. 입금이 반영되는 계정은 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가 청산 중일 때는 사용할 수 없습니다.

퍼프용 빌더 승인​

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

최대 수수료 0%로 Account에 대한 Hyperliquid 빌더를 승인합니다. 모든 Hypercall 퍼프 주문에는 Hypercall 빌더 코드가 포함되므로, 첫 퍼프 주문 전에 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): 호출자 또는 서명자가 매니저가 아님
  • Account__ApiWalletNotActive(address addr): 서명자가 활성 API 지갑이 아님
  • Account__ApiWalletAlreadyActive(address addr): API 지갑이 이미 Account에 등록되어 있음
  • Account__ApiWalletIsManager(): 매니저는 자기 자신의 API 지갑이 될 수 없음
  • Account__NonceAlreadyUsed(address signer, uint256 nonce): nonce 재사용
  • Account__LiquidationInProgress(): 청산 중이라 작업이 차단됨

보안 고려사항​

  1. 매니저 키: API 지갑, 출금, 빌더 승인을 제어합니다. 하드웨어 지갑을 사용하십시오.
  2. API 지갑 키: 주문과 취소에만 서명합니다. 시스템별로 별도의 키를 사용하고 주기적으로 교체하십시오.
  3. Nonce: 서명자마다 고유한 nonce 공간을 가집니다. 밀리초 단위 타임스탬프를 사용하고 오프체인에서 추적하십시오.
  4. 활성화: 퍼프를 거래하려면 먼저 HyperCore에서 Account가 활성화되어 있어야 합니다(최소 $1 상당의 HYPE 입금).
최종 업데이트: