Onboarding to Portfolio Margin

Portfolio Margin (PM) is live on production for allowlisted accounts. It margins your options and your Hyperliquid perps together on worst-case portfolio risk, so a hedged book needs far less collateral than it does under Standard Margin. This page covers how to get onto it. For how the margin itself is calculated, see Portfolio Margin.

In short: use a new manager wallet, get it allowlisted, create its Hypercall account, turn on HyperCore unified account mode, switch to Portfolio mode, and only then deposit.

Why you start from a new wallet

A Standard Margin (SM) account with a balance or an open book cannot be flipped to Portfolio Margin in place. Hypercall accepts a switch to Portfolio mode only when all of these hold for the manager wallet:

Requirement	What it means
Allowlisted	The manager wallet address is on the PM allowlist.
Exactly one Hypercall account	The manager controls one Account contract. None, or more than one, is rejected.
Zero Standard balance	The wallet's Standard Margin cash balance is zero. Any withdrawable balance blocks the switch.
Flat	No open positions and no open orders, on the manager wallet or its Account.

These rules exist because the two modes are different kinds of account, not one account with a setting:

• Your collateral is held differently. Moving from Standard to Portfolio Margin means moving your funds, not flipping a switch.
• Positions are margined under different rules. An open position would have to be re-margined from one set of rules to the other.
• So the switch happens from an empty account. Doing both safely in one step is not supported, which is why the account must be flat and empty first.

Margin mode is set per manager wallet, so one wallet cannot run both modes. The simplest path is a fresh manager wallet for PM, which lets your existing SM account keep quoting while you set up. You can also empty your existing wallet (close everything, cancel all orders, withdraw all Standard cash) and switch it, but you cannot keep that SM book running meanwhile.

Before you start

• A new manager wallet (an EOA you control, ideally on a hardware or otherwise secured key). This is the address that gets allowlisted.
• HYPE on HyperEVM in that wallet, for the account creation deposit plus gas.
• The USDC you plan to use as collateral.

Setup steps

Do these in order. Step 5 must come before step 6.

1. Create a new manager wallet. Do not reuse your SM manager, an API wallet, or an agent key.

2. Request allowlisting. Send the manager wallet address to the Hypercall team, by X or the Hypercall Discord. To check whether it is live, call GET /risk/limits?wallet=<manager>. The response reports portfolio_margin_mode_available: true once the wallet may switch.

3. Create your Hypercall account. From the manager wallet, call createAccount() on the Exchange contract with the HYPE creation deposit. This deploys your Account contract and activates it on HyperCore. See Onboarding (contracts). Create only one account for this manager.

4. Turn on HyperCore unified account mode for the Account. Submit the hl_set_abstraction action, signed by the manager wallet, with user set to your Account address and abstraction set to 2 (unified account). POST /v1/actions/hl_set_abstraction/typed-data returns the exact typed data to sign, and POST /v1/actions/hl_set_abstraction submits it. Wait until HyperCore reports the Account as unifiedAccount. Hyperliquid's other account modes, including its own portfolio margin mode, are not supported.

5. Switch to Portfolio mode. Send POST /margin-mode with wallet set to your manager address and margin_mode set to portfolio, signed by the manager wallet (see Authentication). The response returns your Account address as the PM wallet. Do this before depositing: while a wallet is still in Standard mode, a Hypercall deposit is credited as Standard cash, and that balance then blocks the switch until you withdraw it again.

6. Deposit USDC into your Account. Deposit through the app, which routes by margin mode, or send USDC on HyperCore to your Account address. The funds count toward margin once Hypercall's next HyperCore snapshot shows them.

7. Set up your signing keys. Approvals on your old SM wallet do not carry over.

   • Options (REST): approve your trading key for the new manager wallet with POST /approve-agent. See Agent Authorization.
   • Perps (on-chain directives): register an API wallet on your Account with the manager-signed hc_update_api_wallet action. An API wallet can be active on only one Account. See EIP-712 Signing.

8. Trade. Keep sending your manager address as wallet on options requests; Hypercall routes them to your PM account. Order types, the order API, and signing are the same as on Standard Margin.

In the app, Settings > Margin Mode is shown to allowlisted wallets. Choosing Portfolio there runs steps 3 to 5 for you: it creates the account if you have none, turns on unified account mode, and switches the mode.

If you skip unified account mode

If the Account is not in HyperCore unified account mode, Hypercall cannot read an authoritative equity figure for it. Portfolio reads and orders then fail with an error like missing HyperCore account equity for PM wallet 0x..., and the account cannot trade. Fix it by completing step 4 and waiting for HyperCore to confirm the mode.

FAQ

Can I keep my Standard Margin account running? Yes. Onboard PM on a new manager wallet and leave your SM account as it is.

Why was my margin-mode switch rejected? The error names the rule: the wallet is not allowlisted, it has no Account (or more than one), it has a Standard balance, or it has open positions or orders. See Why you start from a new wallet.

I deposited before switching. What now? The deposit was credited as Standard cash. Withdraw it, then switch to Portfolio mode and deposit into your Account.

Do I need new API keys? You need new approvals. Options agent approvals are tied to the manager wallet, so approve your key again for the new one. A perps API wallet can be active on only one Account, so use a new key or remove it from your old Account first (step 7).

Which wallet address do I give for allowlisting? The manager wallet, not the Account contract and not an API wallet.

Where do I learn how PM margin, liquidation, and settlement work? See Portfolio Margin, Margin Floor, Liquidation, and Settlement.