Papertrade Explorer

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

Unofficial, not affiliated with Papertrade. High leverage can lose your whole margin.

A block-explorer-style site for Papertrade, the fully on-chain 1000x synthetic perps exchange on HyperEVM (chain 999). Paste a wallet, an intent id or a transaction hash and see what happened, live. Read-only: nothing here signs or sends a transaction.

Use it from your AI

A read-only MCP server runs at https://papertrade-explorer.pages.dev/mcp (Streamable HTTP, stateless, no key). Nine tools: search, get_wallet, get_positions, get_intents, lookup_intent, decode_transaction, get_leaderboard, get_trade_history, get_protocol_overview. None of them signs, sends or places anything.

claude mcp add --transport http papertrade-explorer https://papertrade-explorer.pages.dev/mcp

Setup for Claude Desktop and claude.ai, Claude API, Codex, ChatGPT, Gemini CLI, Cursor, VS Code, Windsurf, Zed, Cline, Goose, Continue and OpenAPI frameworks is in Connect your AI. Every tool is also a plain HTTP call: POST /api/tools/{name}, described by /openapi.json.

Discovery files: /.well-known/mcp/server-card.json, /.well-known/agent-card.json, /.well-known/api-catalog, /llms.txt, /llms-full.txt. Registry metadata is in server.json.

Docs

Full documentation lives at papertrade-explorer.pages.dev/docs, with raw markdown in docs/. Add .md to any docs URL for the markdown twin.

Embed and Papertrade OS

Add ?embed=1 for a product-only view. The main page may be framed by papertrade-os.pages.dev and other *.pages.dev hosts: Open in Papertrade OS.

Why

Papertrade positions, intents and leaderboards live behind an API and inside batched BatchExecutor transactions. This explorer makes them linkable, shareable and inspectable. Every wallet has a stable URL with a rich link preview.

What it looks like

A warm paper-toned UI (dark in dark mode) with a serif wordmark, a pulsing Live dot on wallet pages, stat cards, a positions table with bust-distance bars, an area chart for equity or net PnL, and a leaderboard table with gold, silver and bronze rank badges.

Quick start

npm install
npm run dev:site

Open http://localhost:8792. The SDK is installed from the sibling tarball (file:../papertrade-sdk-0.1.0.tgz) until it is on npm.

Features

• Search a wallet, intent id, tx hash or position number. A 64-hex input is tried as a transaction first, then as an intent id. Recent searches are kept in localStorage. Press / to focus search.
• Wallet: live balance, open positions with mark, unrealized PnL, bust price and distance (SDK math), streamWallet live updates, portfolio chart (1h, 1d, 1w, all), trade history with net PnL and PAPER minted, closed positions, queue balances, PAPER held, staked and pending rewards, rank in each leaderboard window, session-key status, copy address and HyperEVMScan link.
• Leaderboard: sort by every column, 24h, 7d, 30d and all-time windows, name or address search, 25 per page.
• Transaction: decodes BatchExecutor calldata (open, close, deposit, withdraw, stake, claim, session key) and verifies each EIP-712 signature by recovery. Shows whether each intent executed.
• Intent: settlement status from the live feed, wallet state and on-chain events.
• Link previews: /w/<address> renders Open Graph tags for the wallet and redirects people to the app.
• Light and dark mode, 360px responsive, keyboard accessible, reduced motion respected.

Architecture

• site/app.ts is a vanilla TypeScript hash router, bundled by esbuild to site/public/app.js.
• src/ holds pure logic (calldata decoding, formatting, query parsing, OG building) and views.
• site/functions/api/papertrade/[[path]].ts is the same-origin proxy (Papertrade sends no CORS headers).
• site/functions/api/rpc.ts is an allowlisted JSON-RPC proxy for HyperEVM with rate-limit retry.
• site/functions/w/[addr].ts is the OG preview function.
• site/functions/mcp.ts is the MCP server and site/functions/api/tools/[name].ts its REST mirror. Shared plumbing is in site/functions/_lib/ and the tool list in _lib/manifest.ts, which also generates the discovery files and docs.
• scripts/build-discovery.mjs and scripts/build-docs.mjs run in build:site.
• A strict CSP is set in site/public/_headers. Only / may be framed, and only by papertrade-os.pages.dev and other *.pages.dev hosts.

Environment variables

Optional PAPERTRADE_API_URL (defaults to https://exchange.papertrade.xyz). No secrets and no paid APIs are used. If you add one, put it in .dev.vars and document it here.

Scripts

npm run typecheck, npm test, npm run build:site, npm run dev:site, npm run deploy:site.

Deploy

npm run build:site && cd site && npx wrangler pages deploy

Known limits

• There is no global position-id lookup. #/position/<id> searches the live feed, otherwise it asks for the owner wallet (#/position/<wallet>/<id>).
• The live feed does not currently include intent ids, so the intent page falls back to wallet state and an on-chain scan.
• lookup_intent scans about the last 6000 blocks. Older intents are found through get_trade_history.
• HyperEVM RPC caps getLogs at 1000 blocks and 1 MiB, and rate limits come back as HTTP 200 with code -32005. The proxy retries.

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. Data is shown as is and is not financial advice. High leverage can lose your whole margin.

Apache-2.0 licensed.

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