papertrade-terminal

Live site · Terminal · Docs · MCP · Issues · Discussions · Papertrade · Toolkit

Unofficial, non-custodial trading terminal for Papertrade, the fully on-chain 1000x synthetic perps exchange on Hyperliquid's HyperEVM (chain 999). Static app plus a tiny same-origin proxy, deployable on Cloudflare Pages.

Unofficial, not affiliated with Papertrade. High leverage can lose your whole margin. Nothing here is financial advice. Review every confirmation dialog before you sign.

What it is

A browser terminal built on papertrade-sdk. Your wallet key never touches the page: you connect an injected wallet (EIP-6963, with a window.ethereum fallback), sign one RegisterSessionKey message, and from then on a session key stored in this browser signs orders. Session keys can open and close positions but can never withdraw.

The screen has a candle chart on the left, the order ticket on the right (Trade, Fund, Swap), and positions, history and pending orders below. On a phone it collapses to a bottom nav (Chart, Trade, Positions, Fund, Swap) with no horizontal scroll at 360px. Light and dark follow prefers-color-scheme; prefers-reduced-motion is honored.

Features

• Wallet: EIP-6963 discovery, window.ethereum fallback, switch or add HyperEVM (999), address and USDC/HYPE balances, designed no-wallet, wrong-chain and rejected states. Watch-only mode with ?watch=0x....
• Session key: generated by the SDK, registered with a wallet signature after a plain-language summary, stored in localStorage with a clear control, expiry shown, re-registered when expired.
• Trading: market selector with live marks, long/short, margin, leverage slider (up to 1000x), pre-trade panel (notional, entry, bust price, what a close pays at several price moves after deadband, impact and fee), validations (min $10 margin, $10,000 notional, per-market caps), confirm dialog, session-key signing, submission through the proxy, intent status and toasts.
• Positions: live table over the wallet SSE stream, close one or close selected (batched at 12 per intent), trade history, pending orders with cancel.
• Charts: lightweight-charts candles with interval switcher (Hyperliquid candles), entry and bust lines for your positions, a TradingView tab (BTC and ETH), and a HYPE/USDC pool tab (native GeckoTerminal candles, with DexTools and GeckoTerminal embed toggles).
• Fund: deposit through buildHyperEvmDeposit (each step signed in your wallet, with the activation fee and minimum shown), withdraw through prepareWithdraw with route (HyperCore or HyperEVM), fee and minimum shown.
• Swap: KyberSwap quote on HyperEVM, route, rate, minimum received, price impact, gas, exact-amount approve, and a transaction your wallet signs.
• Quote ladder: besides the close-outcome table, a leverage ladder shows the bust price and room to liquidation at every leverage step for the live mark.
• Deep links: /?market=BTC&side=long&margin=1000&leverage=10 opens the terminal with the ticket prefilled behind a review banner. ?embed=1 hides marketing chrome so it can run as a window in Papertrade OS.
• Keyboard: B long, S short, / margin, M market, [ ] leverage, 1 to 4 Trade, Positions, Fund, Swap, C chart, ? help, Esc close.

MCP server and AI connectors

A read-only Model Context Protocol server runs at https://papertrade-terminal.pages.dev/mcp (Streamable HTTP, stateless, no key). Nine tools: list_markets, quote_open_position, quote_leverage_ladder, quote_close_position, get_wallet_positions, get_recent_trades, get_candles, get_protocol_status and build_trade_plan. Nothing signs, sends funds or places orders. build_trade_plan returns an unsigned plan plus a deep link that opens this terminal prefilled; the user signs in their own wallet.

claude mcp add --transport http papertrade-terminal https://papertrade-terminal.pages.dev/mcp
codex mcp add papertrade-terminal --url https://papertrade-terminal.pages.dev/mcp

Gemini CLI, Cursor, VS Code, Claude Desktop and claude.ai, ChatGPT, the Claude and OpenAI APIs, Windsurf, Zed, Cline, Goose and Continue are covered in Connect your AI. Discovery files: /.well-known/mcp/server-card.json, /.well-known/agent-card.json, /.well-known/api-catalog, /openapi.json, /llms.txt. Documentation lives in docs/ and is published at https://papertrade-terminal.pages.dev/docs/.

Quick start

npm install ../papertrade-sdk-0.1.0.tgz viem   # SDK is not on npm yet
npm install
npm run dev:site        # builds, then wrangler pages dev on :8788

Open http://localhost:8788. Add ?watch=0xYourAddress to browse an account read-only.

Scripts

Architecture

browser (site/public/app.js + lazy chunks)
  |- PapertradeClient -> /api/papertrade/*  (Pages Function, same origin)  -> exchange.papertrade.xyz
  |- viem public client -> rpc.hyperliquid.xyz/evm        (balances, allowance, receipts)
  |- Hyperliquid info API (candles), KyberSwap aggregator, GeckoTerminal (pool candles)
  |- wallet (EIP-1193): RegisterSessionKey, deposits, withdrawals, swaps
  `- session key (localStorage): open, close, cancel intents

Papertrade sends no CORS headers, so site/functions/api/papertrade/[[path]].ts forwards only the public routes (state and query reads, the SSE stream, signed intent POSTs). It holds no keys. Heavy code (charts, TradingView, swap) loads on demand. A strict CSP lives in site/public/_headers (no inline styles or scripts).

Environment variables

None are required. Optional, in site/.dev.vars or the Pages project settings:

Deploy

gh repo create nirholas/papertrade-terminal --public --source . --push
cd site && npx wrangler pages deploy

(npm run build:site first, or use npm run deploy:site.) The site is expected at https://papertrade-terminal.pages.dev.

The Papertrade toolkit

Nine open-source building blocks for Papertrade, the fully on-chain 1000x perps exchange on Hyperliquid HyperEVM. Use them together or on their own.

Contributing and support

• Found a bug or want a feature? Open an issue.
• Questions and show-and-tell: Discussions.
• Pull requests are welcome, see CONTRIBUTING.md. Security reports go through SECURITY.md.
• If this saved you time, a star helps other Papertrade traders and builders find it.

Built by three.ws.

Disclaimer

Unofficial, not affiliated with Papertrade, high leverage can lose your whole margin. Apache-2.0 licensed. See SECURITY.md.

Built by nirholas · @nichxbt · github.com/nirholas