Skip to main content

Hyperliquid Wallet

Preview and unreleased for general live use

Hyperliquid market data and LocalPaper are Current. Wallet-based Broker routing remains Preview and is not approved for general live use.

Trade only where Hyperliquid is permitted

Perpetuals and other crypto products can be restricted by country, region, or user status. Follow current law where you live and where you are located, plus Hyperliquid's current terms and interface restrictions. Do not connect, deposit, or trade if the activity is not permitted for you. Do not use a VPN or other location-masking tool to bypass a restriction. This page is operational documentation, not legal advice.

Add The Connection And Connect A Wallet​

  1. Open Connections > Configure....
  2. Select Hyperliquid under available connections, then select Add.
  3. Select the new entry under Configured connections and give it a recognizable Name.
  4. Turn Use Testnet on for a test connection. Leave it off only when you intentionally need mainnet.
  5. For market data and LocalPaper only, select OK without connecting a wallet.
  6. For the Preview wallet route, select Connect Wallet in the Credential section.
  7. Open MetaMask and review each prompt. If HyperionX shows a WalletConnect QR code, open WalletConnect inside MetaMask and scan it.
  8. Confirm that Main Wallet Address, Agent Wallet Address, and Builder Approval show the expected result.
  9. Select OK, then open Connections and select the saved connection.

The connected main wallet should be the account you intend to fund and trade. HyperionX generates the separate agent wallet during this flow; do not enter or import a main-wallet seed phrase.

Wallet Model​

HyperionX uses an external wallet to approve a dedicated Hyperliquid API/agent wallet:

  1. The external wallet connects through WalletConnect.
  2. HyperionX generates a new agent private key locally.
  3. The external wallet approves that agent for the selected Hyperliquid account.
  4. HyperionX uses the agent key for approved Hyperliquid trading actions.

HyperionX does not need the seed phrase or private key of the user's main external wallet. Never enter a seed phrase or main-wallet private key into HyperionX, Code Lab, Rion, logs, or support messages.

The Hyperliquid agent key and the Local Desktop API bearer token are separate credentials. A release-enabled local trading client receives only the bearer token. See Local Agent Live Trading API for the additional capability, permission, active-context, and provider gates.

Local Agent-Key Storage​

The generated agent private key is stored locally so the connection can recover after restart. The current Windows build encrypts it with Windows Data Protection API using the current Windows user scope.

This means:

  • another Windows user cannot normally decrypt the stored value
  • moving the application database to another computer or Windows account does not make the key portable
  • compromise of the signed-in Windows user can still expose locally usable credentials
  • device backups and support bundles must be handled as sensitive data

The agent key is a trading credential. Treat it like an exchange API secret even though it is not the main wallet key.

WalletConnect Session Storage​

WalletConnect/Reown session state is separate from the Hyperliquid agent key. The current Windows worker stores its session data in DPAPI-protected files scoped to the signed-in Windows user:

  • %LOCALAPPDATA%\HyperionX\WalletConnect\reown-mainnet.bin
  • %LOCALAPPDATA%\HyperionX\WalletConnect\reown-testnet.bin

A later mainnet deposit flow can restore a compatible saved session and continue without displaying a new QR code. Protection at rest does not protect the session from compromise of the signed-in Windows account.

Builder-Fee Approval​

The Preview connection requests approval for a HyperionX builder code with a maximum builder fee of 0.1% (10 basis points) for eligible routed activity.

Review the wallet signature request before approving it. The approval establishes a maximum; provider behavior and actual fees remain subject to the Hyperliquid transaction and account state.

HyperionX does not publish wallet addresses or private credential values in this documentation. Verify approval details in the wallet and provider interface rather than copying an address from a support message.

Treat provider-side approval as authoritative

Signed 1.1.12-era source can reuse a locally stored builder-approval flag, and an agent-wallet validation request that cannot complete can leave the connection appearing usable. The reviewed post-1.1.12 development source resets stored approval state for the connection, rechecks agent and builder approvals with the provider, and blocks wallet trading when validation cannot complete. That hardening must not be assumed to exist in an older installed build.

In every build, an Approved or connected label in HyperionX is not a substitute for checking the authoritative Hyperliquid account. Before a live action, verify the agent and builder state there. If that provider-side state cannot be checked, treat approval as unknown and do not trade. A revoked agent may ultimately be rejected by Hyperliquid, but an attempted order is not a safe approval test.

Fund The Account Through Bridge2​

HyperionX can send native USDC from the connected wallet on Arbitrum to Hyperliquid's Bridge2 contract. The official Hyperliquid Bridge2 documentation specifies native USDC on Arbitrum and a minimum deposit of 5 USDC. A smaller deposit is not credited and can be permanently lost.

Before starting, the connected main wallet needs:

  • at least 5 native USDC on Arbitrum One
  • enough ETH on Arbitrum to pay the deposit transaction's network fee
  • the same wallet address shown as Main Wallet Address in HyperionX

The official Hyperliquid onboarding guide explains how to move USDC and ETH to Arbitrum. Use native USDC, not USDC.e, USDT, or another token.

Deposit From HyperionX​

  1. Confirm Use Testnet is off. HyperionX enables this deposit flow for mainnet only.
  2. Open Connections > Configure... and select the configured Hyperliquid connection.
  3. Confirm the connected Main Wallet Address.
  4. Select Deposit USDC.
  5. Enter an amount of at least 5 USDC.
  6. Review the amount and official destination shown by HyperionX.
  7. Before signing, confirm in MetaMask that the sending account matches the Main Wallet Address recorded by the connection.
  8. Approve the Arbitrum transaction in MetaMask only after checking the sender, network, token, amount, destination, and fee. A restored WalletConnect session may show the request directly without a new QR code.
  9. Wait for Hyperliquid to credit the bridge deposit, then verify the balance in the authoritative Hyperliquid account before trading.

Before signing, verify the network, token, amount, destination, and network fee in the wallet. An on-chain transfer cannot be undone by HyperionX. Do not make a mainnet deposit merely to test the button.

Sender mismatch is detected after submission

The current desktop passes the amount and network to the wallet worker, then compares the returned sender with the connection's Main Wallet Address only after the transaction has been submitted. A mismatch warning cannot undo that transfer. The wallet's own account display is the required pre-signing check.

Disconnect And Revocation​

Disconnect Wallet clears the in-memory trading association and asks HyperionX to save empty agent-key fields to the connection. The current save is asynchronous and best-effort, so a success label is not proof that the database update persisted. It also does not delete the separate WalletConnect session files or prove that the WalletConnect session, agent approval, or builder-fee approval was revoked remotely or on-chain.

After disconnecting locally:

  1. Close and reopen the connection editor and verify that the wallet and agent fields remain cleared. If they return, stop using the connection and repeat the local cleanup after all HyperionX processes close.
  2. Open the authoritative Hyperliquid account or wallet controls.
  3. Review approved agents and builder permissions.
  4. Revoke permissions that should no longer exist.
  5. Verify there are no unexpected working orders or positions.
  6. If the device should no longer retain a WalletConnect session, close HyperionX and its wallet worker, then remove the exact %LOCALAPPDATA%\HyperionX\WalletConnect data described in Install, Update, And Uninstall. Removing local files does not revoke remote permissions.

Local disconnect and provider-side revocation are separate actions.

Recovery​

On restart, HyperionX validates the stored main-wallet address, derives the agent address from the encrypted key, and attempts to check provider approval where available. Signed 1.1.12-era behavior can retain a locally stored approval when that check cannot complete; the reviewed post-1.1.12 development behavior clears the trusted state and fails closed instead. A deposit can also restore a compatible persisted WalletConnect session without a new QR prompt. If validation fails or the agent was revoked, reconnect the external wallet and approve a new agent.

Do not repeatedly submit orders while approval state is uncertain. Verify the provider account first.

Safe Preview Checklist​

  • Confirm Hyperliquid use and the intended product are permitted in your country and current location.
  • Use testnet where available.
  • Keep Enable Trading off when only market data is required.
  • Confirm the account, network, agent approval, and builder-fee approval.
  • For a mainnet deposit, use the connected wallet, native Arbitrum USDC, at least 5 USDC, and enough Arbitrum ETH for gas.
  • Use LocalPaper until the wallet feature is promoted from Preview.
  • Never share QR payloads, WalletConnect session data, agent keys, or wallet signatures.
  • Revoke provider-side permissions when a device is lost, replaced, or no longer trusted.