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.

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.

USDC Deposit​

The wallet flow can request a native USDC deposit using Arbitrum on Hyperliquid mainnet. Deposits through this flow are mainnet-only and require at least 5 USDC; the worker rejects testnet deposits and smaller amounts.

Before signing:

  • confirm the wallet is on the intended network
  • confirm the asset is the expected native USDC token
  • confirm the amount and destination in the wallet
  • allow for network fees
  • understand that an on-chain transaction cannot be undone by HyperionX

Do not test a mainnet deposit simply to validate the user interface. Use testnet workflows where supported.

Disconnect And Revocation​

Disconnect Wallet removes the local trading association and stored agent-key fields from the HyperionX connection. It does not delete the separate WalletConnect session files, and it does not prove that the WalletConnect session, agent approval, or builder-fee approval was revoked remotely or on-chain.

After disconnecting locally:

  1. Open the authoritative Hyperliquid account or wallet controls.
  2. Review approved agents and builder permissions.
  3. Revoke permissions that should no longer exist.
  4. Verify there are no unexpected working orders or positions.
  5. 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 checks provider approval where available. 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​

  • Use testnet where available.
  • Keep Enable Trading off when only market data is required.
  • Confirm the account, network, agent approval, and builder-fee approval.
  • 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.