papertrade-explorer MCP server
Commit Nov 11, 2026Lets an AI client inspect Papertrade wallets, positions, leaderboards, and decoded transactions on HyperEVM.
Also known as nirholas/papertrade-explorer
- Stars
- 6
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- Apache-2.0
What is papertrade-explorer MCP?
papertrade-explorer lets an AI client inspect Papertrade wallets, positions, leaderboards, and decoded transactions on HyperEVM.
Summary generated from the project's README
About papertrade-explorer MCP server
Analyzing on-chain synthetic perpetual positions and trader performance on HyperEVM is what this read-only MCP server enables. It provides an interface for AI clients to inspect the Papertrade exchange by accessing wallet balances, open positions, and real-time leaderboards. Because it is a stateless, read-only service, it does not sign or send any transactions, making it safe for use with various AI tools.
Developers can connect this server to clients like Claude Desktop, Cursor, or ChatGPT using a simple HTTP transport. The server provides nine specific tools including get_wallet, get_positions, get_intents, and decode_transaction. It allows for deep inspection of BatchExecutor calldata to verify EIP-712 signatures and settlement status. Users can search via wallet addresses, intent IDs, or transaction hashes to see exactly what occurred on the chain.
This tool is particularly useful for those needing to bridge the gap between raw blockchain data and human-readable trading insights. It decodes complex data into clear information about unrealized PnL, bust prices, and trade history without requiring any API keys or paid accounts.
What you can do with it
- 1Audit trader performanceAsk the AI to retrieve the current leaderboard and rank of a specific wallet address.
- 2Inspect specific trade detailsRequest a breakdown of a transaction hash to see if an intent was successfully executed.
- 3Monitor active positionsHave the AI client check a wallet for open positions and their current unrealized PnL.
- 4Verify settlement statusUse the client to look up the settlement status of a specific intent ID.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenirholas/papertrade-explorer is public and reachablegithub.com/nirholas/papertrade-explorer ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/nirholas/papertrade-explorer ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPapertrade 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),
streamWalletlive 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.tsis a vanilla TypeScript hash router, bundled by esbuild tosite/public/app.js.src/holds pure logic (calldata decoding, formatting, query parsing, OG building) and views.site/functions/api/papertrade/[[path]].tsis the same-origin proxy (Papertrade sends no CORS headers).site/functions/api/rpc.tsis an allowlisted JSON-RPC proxy for HyperEVM with rate-limit retry.site/functions/w/[addr].tsis the OG preview function.site/functions/mcp.tsis the MCP server andsite/functions/api/tools/[name].tsits REST mirror. Shared plumbing is insite/functions/_lib/and the tool list in_lib/manifest.ts, which also generates the discovery files and docs.scripts/build-discovery.mjsandscripts/build-docs.mjsrun inbuild:site.- A strict CSP is set in
site/public/_headers. Only/may be framed, and only bypapertrade-os.pages.devand other*.pages.devhosts.
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_intentscans about the last 6000 blocks. Older intents are found throughget_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.
| Project | What it does |
|---|---|
| papertrade-ai | MCP server and CLI: trade Papertrade from Claude, ChatGPT, Cursor and any MCP client |
| papertrade-sdk | Typed API client, live account stream, EIP-712 signing and verified settlement math. |
| papertrade-terminal | Non-custodial web trading terminal with charts, order ticket, funding and swaps. |
| papertrade-analytics | DefiLlama-style dashboard and JSON API: TVL, volume, OI, PAPER economics. |
| papertrade-explorer (this repo) | Linkable wallet pages, decoded transactions and a live leaderboard. |
| papertrade-liquidations | Liquidation map and closest-to-bust feed, recomputed with the verified formula. |
| papertrade-yield | PAPER staking dashboard with realized USDC yield and wallet-signed actions. |
| papertrade-alerts | Know before the liquidation: Telegram, Discord and webhook alerts. |
| papertrade-copytrade | Guard-railed copy-trading CLI. Dry run by default. |
| papertrade-x402 | Pay-per-call intelligence API for AI agents, paid in USDC on Solana or Base. |
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.
papertrade-explorer MCP questions
Is this server capable of executing trades?
No, it is a read-only server that does not sign or send transactions.
What tools are available through the MCP server?
The server provides nine tools: search, get_wallet, get_positions, get_intents, lookup_intent, decode_transaction, get_leaderboard, get_trade_history, and get_protocol_overview.
Does using this server require an API key?
No, it runs as a stateless, streamable HTTP server with no key required.
Can I use this with Claude Desktop?
Yes, you can add it to Claude Desktop using the provided MCP command.