Papertrade protocol reference (unofficial)

This is an independent, community-written reference for building on Papertrade. It is not affiliated with or endorsed by the Papertrade team. The official docs live at docs.papertrade.xyz.

Every number and formula on this page was checked against live mainnet data. The checks run in this repository's test suite (npm test for recorded fixtures, npm run test:live against production). Where something has not been verified, the page says so.

• What Papertrade is
• Deployment
• Units
• Read API
• Live wallet stream
• Writing: signed intents
• EIP-712 schemas
• Intent ids and nonces
• Settlement math
• PAPER and staking
• Deposits
• Withdrawals
• Errors

What Papertrade is#

Papertrade is a fully on-chain synthetic perpetuals exchange on Hyperliquid's HyperEVM (chain 999). It offers BTC and ETH, up to 1000x leverage, and one-click market opens and closes. There is no order book.

• Pricing. Every trade is a synthetic swap against the protocol LP at Hyperliquid's BBO mid, read through a HyperCore precompile. There is no spread, slippage or funding.
• Fees. There is no fee on notional. Winning closes pay an asymmetric impact haircut on the gain, then a 2% win fee. Losing closes pay exactly the loss.
• The LP. The LP starts at $0 and grows from trader losses (the Martingaler design). When the LP cannot cover a win, the payout joins a FIFO queue, and later losses pay it.
• PAPER. Losses mint PAPER, the LP fee-claim token. Staked PAPER earns USDC.
• Balances. USDC lives on HyperCore. Trading state lives in the Exchange contract on HyperEVM.
• Relayer. Traders sign EIP-712 intents. A relayer batches them on chain through a BatchExecutor contract.

Deployment#

Instruments:

Limits come from /state/trading at runtime: minimum margin $10, minimum notional $10,000, maximum notional per position $10M, and maximum leverage 1000x.

Units#

• USD amounts (balances, margin, PnL) are 18-decimal integers serialized as decimal strings ("wad").
• USDC on chain has 6 decimals. Convert with wad = usdc * 10^12.
• Prices are integers in raw units: price = raw / priceScale.
• PAPER has 18 decimals.

Read API#

Base URL https://exchange.papertrade.xyz. Every response is JSON.

• Canonical query strings. The API rejects a query string that is not canonical. Each parameter may appear once, sorted by name, URLSearchParams-encoded, with no unknown keys. canonicalQuery() builds one.
• No CORS headers. Browser apps on another origin need a same-origin proxy. Every papertrade-* site ships one as a Cloudflare Pages Function.

Price tiles#

Price history is served as fixed tiles at three resolutions, and a request must cover exactly one tile:

planPriceTiles() picks the finest tier whose retention still covers the window and keeps it under 5000 points. It returns the aligned tile requests. mergePriceTiles() joins the responses, and toOhlc() buckets them into candles.

Live wallet stream#

GET /state/user/live?wallet=0x... with Accept: text/event-stream streams a wallet's state.

• liveness events carry {heartbeatIntervalMs}. Treat 3x that interval (capped at 45 s) of silence as a dead connection.
• The first wallet event is a full snapshot. It carries balances, funds, paper {balance, staked, pendingBase, rewardDebt}, lifetime totals, sessionKeys [[key, expiry]], openPositions and operations.
• Later wallet events are patches carrying baseAccountRevision. A patch applies only when baseAccountRevision equals the current accountRevision. Anything else means you are out of sync: reconnect and take a fresh snapshot.

Position tuple: [positionId, instrumentId, isLong, useDebt, entryPriceRaw, marginRaw, leverage, bustPriceRaw, openedAtMs, intentId].

streamWallet() implements all of this, including reconnect with backoff. fetchWalletState() resolves the first snapshot.

Writing: signed intents#

Every write is an EIP-712 message signed off-chain and posted to POST /intents as { action, signed, ...extra }.

• signed is the message in wire form: uints become decimal strings, addresses and bytes become lowercase hex, bools stay bools. v, r and s are added alongside.
• The relayer recomputes the intent id, admits or rejects the intent, and batches it on chain.
• The receipt echoes action and intentId. A client should check both match.

Session keys#

• Registering. The wallet signs RegisterSessionKey once for a locally generated key, with feeAddress = 0x0 and an expiry up to 30 days out.
• What a key can do. It signs opens and closes with no wallet prompt.
• What it cannot do. It cannot withdraw, stake, unstake or claim.
• Revoking. Revoke a key on chain with revokeSessionKey from the wallet.
• Intent lifetime. Every intent's deadline is at most one hour out.

Verified on mainnet:

• A Close intent signed by a key the wallet never registered is rejected with 403 unauthorized_intent. The relayer accepts the wire format and checks authorization.
• A real batched Close from tx 0xde30ba04...f1d9 recovers the trader's registered session key under the exchange domain below.

Opening#

OpenPosition.size is the margin in wad (not notional). leverage is an integer.

PapertradeTrader.validateOpen() checks the same limits the relayer enforces, so the user gets a plain-language error before signing. It checks:

• whether trading or the market is paused,
• whether the intake action is enabled,
• maximum leverage,
• minimum margin and minimum notional,
• maximum position size,
• the side's OI cap, when you pass markPriceRaw (OI and caps are base-asset quantities, so the check needs a price).

Closing#

Close.positionIds takes up to 12 ids per intent. The SDK dedupes ids and splits larger closes into batches.

EIP-712 schemas#

Domains (all version fields are strings):

The exchange domain name is literally String. A mainnet Close signature recovers to the trader's session key only under that name, and the test suite asserts that other names fail. The PaperStaking domain hashes to 0x71706d56c8b436981e93987cd97df512528491b243c6d8d1614cad52659e7eb0, the value PaperStaking.DOMAIN_SEPARATOR() returns on chain.

RegisterSessionKey(address user,address key,uint64 expiry,address feeAddress,uint256 nonce,uint64 deadline)
OpenPosition(address user,uint32 instrumentId,bool isLong,uint128 size,uint32 leverage,bool useDebt,uint256 nonce,uint64 deadline)
Close(address user,uint256[] positionIds,uint256 nonce,uint64 deadline)
WithdrawToCore(address user,uint256 amount,uint256 nonce,uint64 deadline)
Stake(address user,uint256 amount,uint256 nonce,uint64 deadline)
Unstake(address user,uint256 amount,uint256 nonce,uint64 deadline)
Claim(address user,uint256 nonce,uint64 deadline)
Distribute(address user,uint256 nonce,uint64 deadline)
CancelIntent(address user,bytes32 intentId,uint256 deadline)

Intent ids and nonces#

digest   = EIP-712 hash of the message under its domain
intentId = keccak256( keccak256("papertrade:intent-id:v2") ++ digest ++ signerAddress )

This reproduces the intent ids the relayer records for mainnet intents.

Nonces only need to be unique per (user, lane):

• Lanes. PAPER actions use the paper lane. Everything else uses the session lane.
• Seeding. The official client starts each lane at a random 24-bit value times 256 and increments it by one per intent.
• Persistence. NonceAllocator does the same and persists through any localStorage-shaped store.

Settlement math#

Here e is the entry price (raw), x the exit price (raw), L the leverage, and notional = margin * L. Instrument parameters come from /state/trading:

All are wad except maxLeverage.

Bust (liquidation) price#

The bust price is exact in integer math and matches all 205 sampled live positions to the raw unit.

long:  p0 = ceil(e * (L - 1) / L);   bust = floor(p0 * (1e18 + bustBuffer) / 1e18)
short: p0 = floor(e * (L + 1) / L);  bust = ceil(p0 * (1e18 - bustBuffer) / 1e18)

bustBuffer is about 0.048%, so liquidation fires slightly before the zero-equity price. Crossing the bust price is a hard bust: the full margin is forfeited.

Winning close#

This matches 15 of 15 leaderboard settlements to float precision.

deadband = floor(e / 50000)                        (integer raw units)
gainRaw  = (isLong ? x - e : e - x) - deadband
move     = gainRaw / e
scale    = (1 - baseRate) / (1 + 1/(move * rateMultiplier) + referenceNotional/(1e6 * move * positionMultiplier))
adjusted = notional * move * scale                 (= adjustedPnlRaw)
winFee   = adjusted * 0.02                         (= userPaidFeeRaw)
net      = adjusted * 0.98

Small moves keep a small fraction of the raw gain, and large moves keep most of it. If gainRaw <= 0, the close pays nothing.

Losing close#

loss = notional * |x - e| / e        (no deadband, no haircut, no fee on the trader)
paperMintBasis = loss * 0.98         (queue empty: the 2% LP-side fee is carved from the LP's gain)

Liquidation#

loss = margin
paperMintBasis = margin              (verified on mainnet Liquidated rows)

PAPER minted#

paperMinted = paperMintBasis * rate, where:

rate = 100                                     while trackedLp < $2,000,000 (including underwater)
rate = 100 * (S / (S + H))^2                   otherwise, S = $120,000,000, H = tailProgress

trackedLp and tailProgress come from /query/protocol/summary (paper.trackedLp, paper.tailProgress).

PAPER and staking#

• Transfers. PAPER cannot be transferred at launch. It can only be staked and unstaked through intents.
• What stakers earn. Staked PAPER earns USDC: 1% of the realised PnL of settled trades while no payouts are queued, plus the LP overflow above the $5M staker reward cap.

Pending reward, exact against PaperStaking.pendingReward(user):

pending = pendingBase + staked * accRewardPerShare / 1e27 - rewardDebt

• staked, pendingBase and rewardDebt come from the live wallet stream's paper object.
• accRewardPerShare comes from /state/trading (or on chain).
• The precision is 1e27, not 1e18.

PaperStaking exposes pendingReward(address), accRewardPerShare(), totalStaked() and DOMAIN_SEPARATOR().

Deposits#

Each wallet has a personal CREATE2 deposit address:

DepositProxyFactory.computeProxyAddress(user)

USDC that reaches that address on HyperCore is swept into the trader's balance. POST /funding/deposits/check asks the relayer to sweep now.

• Minimum. At least 10 USDC must arrive after fees.
• Activation fee. The first deposit pays a one-time 1 USDC activation fee.

Routes:

• From HyperCore. Send spot USDC to the deposit address with a HyperCore spotSend, signed by the wallet. buildHyperCoreDeposit() builds it.
• From HyperEVM. Approve CoreDepositWallet for USDC, then call depositFor(depositAddress, amount, 4294967295). That moves USDC from HyperEVM onto HyperCore for the deposit address. buildHyperEvmDeposit() returns the exact calls.
• From other chains. Ethereum, Arbitrum and Solana bridge through Circle CCTP. Robinhood Chain USDG bridges through Across. Both land on HyperEVM or HyperCore first.

Withdrawals#

WithdrawToCore is signed by the wallet. amount is in USDC units (6 dp) and must not exceed funds.availableBalance from the live stream (converted to 6 dp).

• Activation fee. If the wallet has never withdrawn (lifetime.withdrawnRaw == 0) and /query/accounts/{w}/funding reports coreAccount: false, 1 USDC is deducted for HyperCore account activation.
• Minimum. After that fee, at least 10 USDC must be sent.
• Route hypercore. Funds land in the wallet's HyperCore spot balance.
• Route hyperevm. The request also carries an onward sendAsset HyperCore action to the USDC system address 0x2000000000000000000000000000000000000000, signed by the wallet, for sent - 0.1 USDC (gas allowance). The relayer submits it after the withdrawal lands, and POST /intents/{id}/onward retries it.

Errors#

Errors come back as { code, reason?, message? }. admission_rejected carries a reason:

Other codes:

• invalid_intent
• deadline_expired
• unauthorized_intent
• intent_not_found
• intent_conflict
• below_minimum_withdrawal
• below_minimum_paper_stake
• intake_action_paused
• invalid_onward
• rate_limited (HTTP 429, honor Retry-After)

PapertradeApiError maps all of them to plain-language messages.

Raw Markdown: /docs/protocol.md