Skip to main content

Connect on-chain (wallets & Hyperliquid)

Connect a wallet (Privy, MetaMask, WalletConnect, or external) and bind it to Hyperliquid for on-chain perpetuals trading.

Find it at: /account/wallets

1. Two-part flow​

Going on-chain in Alphio is two steps, not one:

  1. Add a wallet — make a wallet usable inside Alphio (Privy embedded, MetaMask, WalletConnect, or an external address you control).
  2. Bind to Hyperliquid — create an agent-wallet permission on Hyperliquid so Alphio can place perpetual orders on your behalf.

You can add a wallet and skip the Hyperliquid bind if you only want to view balances. Conversely, the Hyperliquid bind requires a wallet to already be added.

2. Add a wallet​

  1. Go to /account/wallets.
  2. Click Add wallet. The wallet-source picker opens.
  3. Choose one of four sources:
    • Privy — Alphio's embedded wallet provider. Best for new users; no extension or app needed. Recovery is tied to your Alphio login.
    • MetaMask — browser-extension wallet. Approve the connection request in the MetaMask popup.
    • WalletConnect — connect any mobile wallet by scanning a QR code with that wallet's app.
    • External (read-only) — paste a public address to track balances and positions. Cannot sign transactions.
  4. Approve the connection / signature request in the chosen wallet.
  5. The wallet appears under /account/wallets with its address and source label.

Wallet connector picker

3. Bind to Hyperliquid​

Hyperliquid is a high-performance perpetual-futures DEX. To trade it through Alphio, you authorize an agent wallet: an additional key pair that Hyperliquid trusts to place orders on behalf of your main wallet. Your main wallet retains custody of funds — the agent wallet can only place trading actions, not withdraw.

To bind:

  1. On /account/wallets, find the wallet you want to use and click Bind to Hyperliquid.
  2. Sign the Hyperliquid agent-wallet authorization message in your wallet (MetaMask popup, Privy modal, or WalletConnect prompt).
  3. Alphio stores the agent-wallet credentials server-side and confirms the bind.

Once bound, you can place Hyperliquid perpetual orders from chat, watchlist, or the Trade Modal.

Hyperliquid bind

Security note: the agent wallet cannot withdraw funds from your Hyperliquid account. Withdrawals always require a signature from your main wallet.

4. Manage and remove wallets​

All wallet management lives at /account/wallets. For each wallet you can:

  • View — current balances and Hyperliquid bind status.
  • Rebind — re-sign the Hyperliquid agent message if it has expired.
  • Unbind Hyperliquid — revoke the agent wallet without removing the wallet itself.
  • Remove wallet — disconnect entirely. For Privy wallets, removal does not destroy the underlying wallet; you can re-add it later with the same recovery path.

5. Known issues​

warning

The list below is best-effort. Some platform / wallet combinations may have additional caveats. Confirm with the product team if you hit a wallet pairing not listed here.

  • WalletConnect session expiry — sessions time out; reconnect from /account/wallets if signing requests stop reaching your phone.
  • Mobile Safari + extension wallets — extension-based wallets (MetaMask) are not available in mobile browsers. Use the mobile app via WalletConnect instead.
  • Hyperliquid agent re-authorization — agent-wallet permissions are time-bounded by Hyperliquid. If orders start failing with an authorization error, rebind from /account/wallets.
  • External (read-only) wallets — can never bind to Hyperliquid since they cannot sign transactions.
Agent Instructions: Querying This Documentation

If you need information not on this page, you can query the docs dynamically by sending a GET request with the ask query parameter:

GET https://docs.alphio.ai/get-started/connect-on-chain.md?ask=<question>

The question should be specific, self-contained, and written in natural language. The response includes a direct answer plus relevant excerpts and sources.