Concepts#

The terminal does not reimplement protocol math. Every formula below comes from papertrade-sdk, which is verified against recorded live positions. These notes explain what the numbers on screen mean.

Raw prices and the price scale#

Papertrade stores prices as integers. Each market has a priceScale (for example 10, 100 or 1000000) and a raw price is price x priceScale. The terminal and the MCP tools convert for display, so you always see USD prices. When you build your own integrations, never compare a raw price to a USD price.

Margin is a wad#

Margin and balances are 18-decimal fixed point numbers ("wads"). USDC on HyperEVM has 6 decimals, so deposits and withdrawals convert between the two. Open interest and cap fields on a market are in base-asset quantity, not USD, and are priced with the current mark.

Notional and leverage#

notional = margin x leverage. A $50 margin at 10x controls $500 of exposure. Leverage runs from 1x to the market maximum (up to 1000x). The relayer enforces a minimum margin, a minimum open notional, a maximum position notional per market, and per-side open interest caps. The live values come from the trading state, and the get_protocol_status tool reports them.

Entry and the mark#

Papertrade fills at the mark: the Hyperliquid best bid and offer mid that the protocol settles on. The order is accepted into a queue and processed by the relayer, so the fill price is the mark when it is processed, not the instant you press confirm.

Bust price (liquidation price)#

The bust price is where the position is liquidated and the entire margin is forfeited. It is computed with two roundings and a per-market buffer (bustBufferRaw, a few basis points):

Long: p0 = ceil(entry x (L - 1) / L), then bust = floor(p0 x (1e18 + buffer) / 1e18)
Short: p0 = floor(entry x (L + 1) / L), then bust = ceil(p0 x (1e18 - buffer) / 1e18)

The SDK's liquidationPriceRaw matches 205 of 205 recorded live positions. At 1000x the bust price is within a fraction of a percent of entry, so a tiny adverse move liquidates you.

Deadband#

When you win, Papertrade treats the exit as slightly worse than it was: by entry / 50000 (0.002 percent). Moves smaller than this pay nothing. The pre-trade panel and the quote_close_position tool apply it for you.

Impact haircut#

Wins are scaled down by a factor that depends on the size of the move, the market's rate multiplier, its position multiplier and its reference notional:

kept = (1 - baseRate) / (1 + 1/(move x rateMultiplier) + referenceNotional / (1e6 x move x positionMultiplier))

Large wins on small positions keep a smaller fraction than moderate wins. Losses are paid 1:1 and are never haircut. The keptFraction field in quote_close_position is this factor.

The 2% win fee#

After deadband and haircut, a 2% fee is taken from the win. Losses pay no fee. Net PnL on a close is therefore raw win, adjusted, minus 2% for a win, the raw loss for a loss, and the full margin lost if the exit crosses the bust price.

Session keys: trade, never withdraw#

The wallet signs RegisterSessionKey once (30 day expiry, zero fee address). The session key then signs OpenPosition, Close and CancelIntent. The wallet itself must sign WithdrawToCore, Stake, Unstake and Claim. So a stolen or leaked session key can trade your balance but cannot move funds out. The terminal stores the key in localStorage and shows its expiry. Clear it from the Trade tab to revoke local access, and re-register when it expires.

Intents, the queue and the relayer#

Every action is a signed intent posted to POST /intents. The relayer validates it, queues it, and processes it against the live mark. States are queued, prepared, confirmed, and on failure failed, expired or cancelled. An intent can be cancelled only while it is queued. Each intent carries a nonce and a deadline one hour out. The terminal tracks outcomes on the wallet's live SSE stream (/state/user/live) and shows them as toasts and in the Pending table.

Closing in batches#

You can close one position or several at once. A single close intent carries at most 12 position ids (MAX_CLOSE_BATCH), so "close selected" splits larger selections into batches of 12.

Funding#

The first deposit pays a 1 USDC activation fee. A withdrawal has a 10 USDC minimum after fees, and the HyperEVM route needs two signatures and a 0.1 USDC gas allowance. The terminal shows route, fee and minimum before you sign.

Papertrade allows up to 1000x leverage. A small move against the position liquidates it and the whole margin is lost. This is not financial advice. This project is unofficial and not affiliated with Papertrade.