Sub-wallets & multi-exchange

🟡 Intermediate — sub-wallets hold real funds. Each one is bound to a single exchange when created and that choice is permanent for the life of the wallet.

A sub-wallet is an isolated perps account. You can have several of them — Wallet A on Hyperliquid for manual swings, Wallet B on Lighter for a copy-trading bot, Wallet C on Hyperliquid set aside for a specific narrative. Each one has its own equity, positions, open orders, and trading history. They never share balances; what you put in one stays in that one until you withdraw or transfer.

The sub-wallet you trade against also decides which exchange the trade lands on. Switch the wallet, and the next long BTC routes to a different venue automatically — no flag, no toggle.

Currently available exchanges

Today you can bind a sub-wallet to one of the following venues. More are on the roadmap; the SupportedExchange value on the API may extend over time, so integrations should tolerate values outside the current set rather than asserting an exact match.

In the Create Sub-wallet modal these show up as small chips next to each option:

• Better liquidity — Hyperliquid
• Lower fees — Lighter

🟢 Recommended for first-time users: start on Hyperliquid. The deeper book absorbs your fills without slippage on the size most users trade, and the coverage matters more than the small fee difference until you're moving real volume.

Lifecycle: creating → active → error

When you create a sub-wallet the upstream needs a moment to provision the on-chain wallet on the bound exchange. During that window the wallet appears in your picker with a creating badge — disabled for trading, table views render the empty state. It typically lands within a minute.

• creating — provisioning. The wallet appears but isn't yet usable. Picker option is greyed out. Tables show empty rows.
• active — ready. Trade, deposit, and withdraw work normally.
• error — provisioning failed. The recommended action is to remove the failed sub-wallet and create a fresh one; the underlying upstream issue is usually transient.

Creating a sub-wallet

From Portfolio → Perps tab, click + Create sub-wallet in the header. A modal opens with two fields:

• Name — up to 20 characters, any script. Use something you'll recognize at a glance (BTC swing, Lighter test).
• Exchange — Hyperliquid or Lighter, shown with their chip labels (Better liquidity / Lower fees).

Submit. The new wallet appears in the picker immediately with a creating badge and flips to active once the upstream returns. You don't need to refresh; the picker polls the sub-account list every 15 seconds.

You can also create from the Spot tab — the + icon next to the Perps Value card's wallet picker opens the same modal. Useful when you're managing the new wallet's deposits before its first trade.

Renaming a sub-wallet

Names are display-only — you can rename freely without affecting the wallet's address, exchange binding, or any open positions.

Select the wallet in the picker, then click the ✎ pencil icon. The modal pre-fills the current name with the field selected so your first keystroke replaces the whole value. Submit; the new name shows everywhere that wallet is referenced (picker, equity card, Deposit / Withdraw modals).

Two safeguards worth knowing:

• The rename target is snapshotted at click time. If you change the picker selection mid-edit, the modal still commits the rename against the wallet you originally clicked the pencil for.
• If the wallet has been removed in another tab between when you opened the modal and when you tried to submit, the modal shows a short "no longer exists" notice and lets you close it. Nothing gets renamed to a stale target.

The rename button is also available next to the wallet picker in the Perps Value card, so you can rename from the Spot tab too.

Switching wallets across the portfolio

There's a single wallet picker, surfaced in two places:

• Portfolio Perps tab header — visible only on the Perps tab, next to Rename and + Create.
• Perps Value card title row — visible on both Spot and Perps, alongside the equity numbers.

Both surfaces read and write the same ?wallet=<address> URL parameter, so a pick made in one updates the other instantly. The URL is also a shareable / refreshable deep link — drop the selection into chat, hand it to a teammate, or just rely on back-button to return to it.

Your last explicit pick persists to localStorage too. Refresh the page, come back from another route, or restart the browser — the picker defaults to your most recent selection rather than the first wallet in the list. Deep links (?wallet=… in the URL) still win; localStorage is the fallback when the URL is empty.

Per-wallet equity, positions, and orders

When a wallet is selected, the Perps Value card scopes its numbers to that wallet:

• Available to Trade — withdrawable balance on the bound exchange.
• Account Equity — net worth in this sub-wallet.
• uPnL — unrealized PnL across open positions.

Below the card, every perps table — Position, Open Orders, Trade History, Funding History, Order History — scopes to the same wallet. Switch the picker and the tables show their loading skeleton briefly before the new wallet's data lands, instead of flashing the previous wallet's rows.

Total Value (the headline above the cards) aggregates across sub-wallets and includes Spot. It doesn't shift when you change the picker — only the Perps Value card does.

Trading executions across exchanges

All perps actions go through one unified API: /v1/trading-gateway/*. You don't pick a venue per trade — the target exchange is inferred from the sub-account you trade against:

• POST /v1/trading-gateway/place-orders — open / close / attach TpSL
• POST /v1/trading-gateway/cancel-orders — batch cancel
• POST /v1/trading-gateway/modify-order — adjust price / quantity / trigger on a live order
• POST /v1/trading-gateway/update-leverage — leverage + margin mode in one call
• POST /v1/trading-gateway/update-isolated-margin — top up or claw back isolated margin
• POST /v1/trading-gateway/withdraw — USDC withdraw (TOTP required when enabled in Settings → Security)
• GET /v1/trading-gateway/summary — equity + positions + open orders for a sub

When you say "long BTC" in chat, the agent submits a place-orders call with the currently-selected sub-account id. That id's bound exchange is implicit; you never need to pass an --exchange flag.

If you want to trade on a specific wallet without switching the picker first, name it in the prompt:

long BTC with 5x on Wallet A
short ETH on the Lighter wallet

The agent disambiguates by the wallet name + exchange and picks the right sub.

Deposit & withdraw

The Deposit modal picks the destination by sub-wallet, not by exchange. Each option in the wallet dropdown shows the exchange logo, the name, and the wallet's deposit address. Both Hyperliquid and Lighter currently accept USDC on Arbitrum.

The Withdraw modal works the same way — pick the source wallet, enter the amount and destination address, confirm. If you've enabled withdraw 2FA in Settings → Security, the modal prompts for your 6-digit code before submitting; if you haven't enabled it, the code field is skipped.

Known caveats

• Sub-wallet exchange binding is permanent. If you want a wallet on a different venue, create a new one — there's no in-place migration.
• Aggregated portfolio reads (sums across all sub-wallets) still prioritize the Hyperliquid default-dex view today; we're working on full Lighter-aware aggregation. Per-wallet views (when a specific wallet is selected) are already exchange-aware and accurate.
• Each sub-wallet has its own EOA on its bound exchange. There's no internal-transfer shortcut between subs on different exchanges yet — to move USDC, withdraw to your spot wallet, then deposit into the target sub.