Using the app

This chapter goes through the app page by page: what each page is for, where its numbers come from, and what it can ask you to sign. It describes behaviour rather than layout, which changes more often. Each section ends with the chapter that explains the mechanism underneath.

Before you start

Signing in

When the build has a Privy app id (NEXT_PUBLIC_PRIVY_APP_ID), you sign in with email or a wallet. Signing in by email creates an embedded wallet if you have none. Without Privy, the app offers browser wallets, plus MetaMask, Rainbow and WalletConnect when a WalletConnect project id is configured.

The top bar shows the network you are on. On any other network it shows a "Wrong network" button that switches you to Robinhood Chain; pressing an action does not switch for you. Development builds also accept a local test chain (id 31337).

Sample data

Pages read the Levee API. In a development or staging build (FIXTURES_ALLOWED), a page whose API call fails falls back to built-in sample data and shows a "Sample data" tag; sample positions belong to one demo address, so any other address sees an empty book. A production build never shows sample data: it shows empty values and a "Data is not loading" notice with a Try again button.

How a write is sent

1. 01
   Check

   The app checks the wallet, the network and that the contract is deployed, and stops with the reason if one is missing.
2. 02
   Simulate

   It runs the call as an eth_call. A revert stops here, with the reason in a toast, before your wallet opens.
3. 03
   Confirm

   Your wallet asks you to confirm. Rejecting it shows as "Rejected in the wallet".
4. 04
   Send

   Once the transaction has a hash, a toast links to it in the explorer.
5. 05
   Refresh

   The affected data reloads 1.5 s, 4 s and 10 s later, so the indexer has time to catch up.

Approvals come first when a token needs one. They are for the exact amount; an existing allowance of a different size is reset to zero first, as some tokens require. Permit2 is used only for the Uniswap Universal Router and the v4 position manager, and its allowance expires after 30 minutes. Approvals are the one step that waits for the receipt before the next button unlocks. Slippage defaults to 50 bps for a spot trade and 100 bps for a zap; above 500 bps you have to tick an acknowledgement first.

Perp orders

Every perp action (set up, place, cancel) is an EIP-712 message you sign, with a fresh nonce and a timestamp. The server decides the venue: sim, the default, is an in-memory practice book; lighter sends real orders to Lighter.

To trade on Lighter, deposit USDG to Lighter from your wallet first. The app then asks for three signatures: one that asks the signer service for your order key, one over the key change Lighter requires, and one that sends it to be registered with your Lighter account. The key can place and cancel orders and cannot withdraw. See Perpetuals.

The tour

The landing page's "Take the tour" opens /markets?tour=1, an 18-step walk through Markets, Trade, Swap, Pools, Earn, Launch, Portfolio, Stocks, Protocol, Ideas and the Planner. It moves between pages for you; Esc ends it and the arrow keys step through it. Your place is kept in the browser until you finish or end it. The Planner also has its own short guide.

Trading pages

Markets

A ranked list of every asset across public Uniswap pools and Lighter perps, for finding where liquidity earns. Rows come from GET /radar and show price, 24h change, pool fee APR, funding and carry: the pool's fee APR plus a year of the perp funding rate, shown only when the asset has both a pool and a perp market (8 % and up is worth watching, 20 % and up is strong). Tabs narrow the list to Crypto, Tokenized or Seasoned, and a search field filters it. Levee's own pools sit in a separate block under the list. The Seasoned label marks a token whose pool is at least 3 days old, with a market cap above $1M and 100 or more trades in the last 24 h (isEstablished in the code); it is a label, not a gate.

Selecting a row opens its market brief beside the list: carry as one bar split into pool fees, funding received and hedge cost, with pool depth and perp open interest under it. The brief has three actions. Trade opens the asset on Trade, Plan opens it in the Planner, and Hedge opens inside the brief and pairs an LP position with a perp short sized to its delta: it sends you to Trade to provide the liquidity, then signs the short as a perp order. A ?basis= link selects that asset. Read Perpetuals and Hedged vaults.

Trade

A terminal for one asset. A market bar across the top shows the price, 24h change, funding and open interest; click the asset name or press / to switch markets. The ticket has four modes, Spot, Perp, Limit and Liquidity, with a Buy and Sell (Long and Short) toggle; the chart sits beside it, with Positions, Orders, History, Funding and Ideas tabs under it. On a phone the ticket opens from a Trade button. The page reads GET /radar, GET /markets and GET /candles, and before it builds a spot trade it checks the pool's price on chain against the API's.

• Spot. The default path is the Uniswap Universal Router (approve to Permit2, then execute), which pays a 25 bps Levee fee from the output. When the Levee Router pays more on a live quote, the trade goes through Router.swapExactIn instead, with one approval and no Levee fee.
• Perp. Size by notional or by risk budget, leverage from 1x to the market's maximum (3x by default), market or limit, reduce-only, optional stop-loss and take-profit. Market orders carry a 1 % price tolerance. The liquidation price shown is an estimate, not Lighter's figure.
• Liquidity. One token in, a Uniswap range out, through LeveeZapV3.zapMint or LeveeZapV4.zapMint (25 bps of the input). Range shapes are Spot, Curve, Wide and Custom; a stock pool's range widens while the market is closed.
• Limit. RangeOrders.place parks a one-sided position that sells as the price crosses it; it works on Uniswap v3 pools. Where the asset has a Levee DLMM pair, the page links to its limit orders.

Your positions on the page can be closed, collected (collect), removed (v3: decreaseLiquidity, then collect; v4: one modifyLiquidities call), enrolled for automation (PositionKeeper.enroll) or cancelled (RangeOrders.cancel). Read Swaps and routing, One-token deposits and Limit orders.

Swap

Any token for any token through the Levee Router, which splits a trade across Levee pools, public Uniswap v4 pools and Pons curves. Quotes come from Router.quoteExactIn; without a deployed Router, routes are estimates and cannot be sent. The write is an exact approval to the Router, then Router.swapExactIn; native ETH needs no approval.

Price impact of 1 % or more shows a warning, 5 % or more needs your acceptance, and 15 % or more is refused. Slippage defaults to 50 bps and the deadline is 20 minutes. You can paste any token address, and the ?in=, ?out= and ?amt= parameters make a swap shareable as a link. No Levee fee is added. Read Swaps and routing.

Liquidity, launches and your positions

Pools

Levee's own pools: DAMM (dynamic-fee Uniswap v4 pools), DLMM bin pairs and stock pools banded to a Chainlink price. Data comes from GET /pools, GET /pools/:id and GET /stocks.

• Create a pool, one permissionless transaction: DammHook.createPool, DlmmFactory.createPair or StockHook.createPool.
• DLMM pairs. Add liquidity over a chosen number of bins in a Spot, Curve or Bid-Ask shape (DlmmPositionNFT.mint), or place, claim and cancel a limit order (DlmmLimitOrders).
• DAMM and stock pools. Add a full-range or custom-band position through the v4 position manager.

A stock pool also shows its oracle price, the gap between pool and oracle, the band and the market session. Read Levee pools.

Earn

Every vault in one list, filterable by kind. It reads GET /vaults, GET /amm/vaults, the graduated vaults from GET /launch, and share balances and previews on chain.

• LP vaults: approve, then deposit; withdraw with redeem.
• DLMM and stock vaults: deposit both tokens, or one token into a DLMM vault through DlmmVaultZap; withdraw to both tokens or, for DLMM, to one.
• Hedged vaults: approve, then deposit, like an LP vault. The card and the deposit drawer say where the hedge margin is: on Lighter, in an account the vault's funder key controls.
• Protected SPY note: approve, then deposit. It opens once SPY Hedged has sent its first hedge report, and while SPY Hedged is paused the app holds both deposits and exits. Leaving before maturity costs 0.5 %, and the withdraw drawer shows the amount after the fee.
• Income NVDA note is listed as Coming soon and refuses deposits: it is not open yet.

A deposit is also blocked when a vault is paused, its hedge report is stale, a hedged vault has never been reported on, or it is past maturity or settled. A vault's own page shows its range or bins, its keeper and its recent rebalances; only the keeper can rebalance. Read Vaults, Hedged vaults and Structured notes.

Launch

Three tabs, Launch, Graduation and Pons, fed by GET /launch, GET /pons and on-chain reads.

• Launch creates a fixed-supply token and its locked ETH pool in one transaction (LaunchPools.launch), with an anti-snipe fee that decays after launch, or opens a pre-launch vault (LaunchVault.open) that pools buyers' ETH and refunds it if nobody launches within 3 days. A launch's pool fees can be collected here; they go to its fee recipient, the creator at launch.
• Graduation tracks a young token and graduates it into a managed vault (LaunchPipeline.track, graduate, both public); counts across the top show how many tokens are tracked, on the clock, ready to graduate and graduated. It also lists pre-market perps: 3x markets on tokens no venue lists, opened with USDG (PreMarketPerp.open, close, createMarket).
• Pons lists Pons tokens. "Open a Levee pool" creates a DAMM pool at the live Pons price; buying and selling hands you to Swap.

Read Launch a token and Graduation and pre-market perps.

Portfolio

Everything an address holds: Uniswap v3 and v4 ranges, DLMM positions and limit orders, vault shares, range orders, perps and automation. It reads GET /portfolio/:address and reads DLMM and vault positions on chain. Remove on a v4 range is one PositionManager.modifyLiquidities call (DECREASE_LIQUIDITY, or BURN_POSITION for all of it, then TAKE_PAIR) that pays the fees out with the liquidity; its pool key and ticks are read from the position manager and its minimums from the pool's StateView price. Add ?as=0x… to view any address read-only.

From here you can harvest, rebalance or unenroll an automated position, enroll a new one, remove liquidity, cancel a range order, withdraw or burn a DLMM position, cancel or claim a DLMM limit order, and close a perp or set its stops. Read Position automation.

More pages

Stocks

Levee's tokenized-stock pools, refreshed every 20 s from GET /stocks: Chainlink price, pool price, the gap between them, the band, the current fee, the market session and TVL. The open or closed status uses NYSE hours on your device's clock. A stock with no pool offers to create one at the Chainlink price (StockHook.createPool). Read Levee pools.

Protocol

Where fees go: fees by token, conversions, buybacks, burned supply and the $LEVEE price, from GET /protocol and live chain reads. Each step has a button anyone can press: FeeRouter.flush, FeeCollector.convert, unwrapWeth or forwardEth, BuybackV2.buyback (with optional ETH of your own) and poke. A call that would revert shows its reason in plain words. Read Buyback and burn.

Ideas

A feed of ideas: a real position with the argument for it, its PnL and a leaderboard, from GET /theses. To post one, pick one of your own positions and write up to 500 characters; you sign the idea (EIP-712, no gas). Mirroring copies an idea: a perp idea becomes an order you confirm and sign, a vault idea opens the deposit, and an LP idea opens Trade with the range filled in. Each idea has its own page with a share link and card.

The referral panel registers your code and binds you to a referrer from a ?ref= link, both on chain. Read Fees and referrals.

Alerts

Watches any address's LP and perp positions. You build a rule in two steps, the wallet and then the rule, from four kinds: nearing a range edge, left its range, funding changed sign, and close to liquidation. Each rule has an on/off switch, and what fired is listed in a history below. Alerts check every 30 s on every page of the app, using live data only, and pause when data is unavailable. Rules and history stay in your browser, and browser notifications are optional. It never trades.

Tools

The four tools share one arrangement: inputs on the left in numbered groups, results on the right as headline figures, a chart, a breakdown table, and a "Use this" row that hands the result to the page that can act on it. None of them signs anything.

Planner

Compares Hold, LP, Hedge and Perp on the same capital, using current market data. Ranges come from the ±5, 25 and 50 % presets or a custom band. "Share scenario" copies the URL, which carries every input. The "Use this" row opens the result: add this range, open the hedge, open the perp, or buy spot. "Guide me" walks through the chart step by step; it only opens when you press it.

Ranges

Compares a tight, a middle and a broad range (±5 %, ±25 % and ±50 % by default) for the same deposit. A calculator: no data, no writes. Each band opens in the Planner. Read One-token deposits.

Backtest

Replays Hold, LP and Hedge over real hourly closes for ETH, BTC or SOL, from the API's candles; there is no generated fallback. You set the fee APR and funding; the period defaults to the last 7 days. "Plan this range" carries the band to the Planner, and "Download CSV" saves the series.

Sizing

Works out a position size from your risk budget and stop distance. Leverage changes only the margin estimate. It sends nothing itself: the result opens the perp ticket on Trade, on the side you chose. Read Perpetuals.