{"id":"7e257a89-8cb9-457d-9e53-3631c206121c","slug":"papertrade-ai","kind":"mcp","name":"papertrade-ai","summary":"Trade Papertrade BTC and ETH perps from Claude, ChatGPT, Codex, Cursor, Gemini CLI and VS Code. MCP server with OAuth, non-custodial session keys and guardrails.","owner":"nirholas","repoUrl":"https://github.com/nirholas/papertrade-ai","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-10T21:31:09.000Z","addedAt":"2026-10-14T05:50:15.068Z","logoUrl":"https://avatars.githubusercontent.com/u/22895867?u=56ece328987410ef7987e2e9b2c9247f735bf751&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","data-analytics"],"tags":["ai-agents","typescript","chatgpt","claude","claude-code","codex","crypto-trading","cursor"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T01:55:58.560Z","sample":false,"url":"https://conduits.dev/tools/papertrade-ai","language":"TypeScript","transports":["stdio"],"install":{"npm":"papertrade-ai"},"requirements":{"env":[{"name":"PAPERTRADE_WALLET","secret":false,"required":false,"description":"Wallet address for read-only access without logging in."},{"name":"PAPERTRADE_PRIVATE_KEY","secret":true,"required":false,"description":"Optional wallet key for headless trading. Only used to sign a session key registration; never stored."}],"upstreamMayCharge":false},"tools":null,"readme":"
\n\n\"Papertrade\n\n# Papertrade AI\n\n**Trade Papertrade BTC and ETH perps from Claude, ChatGPT, Codex, Cursor, Gemini CLI, VS Code and any MCP client.**\n\nOpen-source [Model Context Protocol](https://modelcontextprotocol.io) server with live markets, wallet analytics, liquidation maps, and guarded trading through non-custodial session keys.\n\n[![npm](https://img.shields.io/npm/v/papertrade-ai?style=flat-square&color=0a8f5b)](https://www.npmjs.com/package/papertrade-ai)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.nirholas%2Fpapertrade--ai-0a8f5b?style=flat-square)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.nirholas/papertrade-ai)\n[![License: MIT](https://img.shields.io/badge/license-MIT-0a8f5b?style=flat-square)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-papertrade--ai-0a8f5b?style=flat-square)](https://papertrade-ai.ninabrekkerese.workers.dev/docs/)\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=papertrade&config=eyJ1cmwiOiJodHRwczovL3BhcGVydHJhZGUtYWkubmluYWJyZWtrZXJlc2Uud29ya2Vycy5kZXYvbWNwIn0%3D)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=papertrade&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fpapertrade-ai.ninabrekkerese.workers.dev%2Fmcp%22%7D)\n\n[Website](https://papertrade-ai.ninabrekkerese.workers.dev) · [Docs](https://papertrade-ai.ninabrekkerese.workers.dev/docs/) · [Tools](https://papertrade-ai.ninabrekkerese.workers.dev/docs/tools) · [Security](https://papertrade-ai.ninabrekkerese.workers.dev/docs/security) · [REST API](https://papertrade-ai.ninabrekkerese.workers.dev/docs/rest-api)\n\n
\n\n```\nhttps://papertrade-ai.ninabrekkerese.workers.dev/mcp\n```\n\nOne URL, OAuth 2.1, no API keys. Your wallet signs once to register a session key that **can trade but cannot withdraw**, and the server enforces the limits you choose: margin per trade, leverage, daily size, open positions and markets. Every trade is previewed and needs your confirmation.\n\n## What you can ask\n\n- \"What are BTC and ETH doing on Papertrade right now?\"\n- \"Show me the Papertrade liquidation map for ETH.\"\n- \"Who are the top 10 Papertrade traders this week? What are they holding?\"\n- \"Analyze wallet 0x...: win rate, biggest trade, equity curve.\"\n- \"If I long BTC with $20 at 500x, where is my liquidation price?\"\n- \"Preview a $15 ETH short at 800x, then open it if I confirm.\"\n- \"Close all my BTC positions.\"\n\nOn clients with [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) support (Claude, ChatGPT, VS Code, Goose) results render as an interactive trading card with a live chart.\n\n## Install\n\n| Client | Install |\n| --- | --- |\n| **Claude** (web, desktop, mobile) | Settings, Connectors, **Add custom connector**, paste `https://papertrade-ai.ninabrekkerese.workers.dev/mcp`. [Guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/claude) |\n| **Claude Code** | `/plugin marketplace add nirholas/papertrade-ai` then `/plugin install papertrade-ai@papertrade-ai`, or `claude mcp add --transport http papertrade https://papertrade-ai.ninabrekkerese.workers.dev/mcp` [Guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/claude#claude-code) |\n| **ChatGPT** | Settings, Apps, Advanced settings, **Developer mode**, Create app, paste the URL, OAuth. [Guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/chatgpt) |\n| **OpenAI Codex** | `codex mcp add papertrade --url https://papertrade-ai.ninabrekkerese.workers.dev/mcp` then `codex mcp login papertrade` [Guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/codex) |\n| **Cursor** | [One-click install](https://cursor.com/install-mcp?name=papertrade&config=eyJ1cmwiOiJodHRwczovL3BhcGVydHJhZGUtYWkubmluYWJyZWtrZXJlc2Uud29ya2Vycy5kZXYvbWNwIn0%3D) [Guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/cursor) |\n| **VS Code** (Copilot) | [One-click install](https://insiders.vscode.dev/redirect/mcp/install?name=papertrade&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fpapertrade-ai.ninabrekkerese.workers.dev%2Fmcp%22%7D) or `code --add-mcp '{\"name\":\"papertrade\",\"type\":\"http\",\"url\":\"https://papertrade-ai.ninabrekkerese.workers.dev/mcp\"}'` [Guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/vscode) |\n| **Gemini CLI** | `gemini extensions install https://github.com/nirholas/papertrade-ai` [Guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/gemini) |\n| **Claude Desktop** (local) | Download `papertrade-ai.mcpb` from [Releases](https://github.com/nirholas/papertrade-ai/releases/latest) and open it. |\n| **Windsurf, Zed, Cline, Goose, LibreChat, others** | Streamable HTTP URL above, or stdio `npx -y papertrade-ai`. [Guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/other-clients) |\n\n### Local (stdio)\n\n```json\n{\n \"mcpServers\": {\n \"papertrade\": { \"command\": \"npx\", \"args\": [\"-y\", \"papertrade-ai\"] }\n }\n}\n```\n\nRun `npx -y papertrade-ai login` once to connect a wallet in your browser. Credentials stay in `~/.config/papertrade-ai` (mode 0600). [CLI guide](https://papertrade-ai.ninabrekkerese.workers.dev/docs/cli)\n\n## Tools\n\n| Tool | Access | What it does |\n| --- | --- | --- |\n| `get_markets` | public | Live Papertrade perp markets (BTC, ETH): Hyperliquid mark/bid/ask, 24h change, Papertrade 24h volume, open interest vs caps, max leverage, minimum trade size and whether each market is open. |\n| `get_price_chart` | public | OHLCV candles for BTC or ETH from Hyperliquid (the price source Papertrade settles against), with range stats and a TradingView link. |\n| `get_protocol_stats` | public | Papertrade protocol analytics: TVL, margin, LP, lifetime volume, open positions, fees, PAPER supply and staking, plus daily history (volume, trader PnL, liquidations, users). |\n| `get_liquidation_map` | public | Where open Papertrade positions get liquidated: notional and position count of longs and shorts by price bucket around the current price, with the largest clusters. |\n| `get_leaderboard` | public | Papertrade trader leaderboard for a time window, sortable by PnL, volume, balance and more. |\n| `get_top_trades` | public | The most profitable individual Papertrade positions in a window: who, market, side, leverage, entry, exit and PnL. |\n| `get_recent_trades` | public | The latest opens, closes and liquidations across all of Papertrade, optionally filtered by market or wallet. |\n| `get_account` | public | A Papertrade account: free balance, locked margin, equity, every open position with live estimated PnL, bust price and distance to liquidation, pending intents, session keys and lifetime stats. |\n| `get_trade_history` | public | Closed and liquidated positions for a wallet, newest first, with entry, exit, settled PnL, fees and PAPER minted. |\n| `get_portfolio_history` | public | Equity curve for a wallet over 1h, 1d, 1w or all time. |\n| `calculate_position` | public | Pure math for a hypothetical position: bust price, liquidation distance and settled PnL at a target exit, using the exchange formula (win curve, deadband, 2% win fee). |\n| `get_deposit_info` | public | How to fund a Papertrade account: the wallet's personal deposit proxy address (USDC on HyperCore spot), minimums, the activation fee, and the wallet's current HyperEVM USDC/HYPE balances. |\n| `get_trading_permissions` | public | What this connection may do: connected wallet, whether a trading session is active and when it expires, the guardrails the owner set, and how much of the daily limit is used. |\n| `preview_trade` | trading | Step 1 of 2 for opening a position. |\n| `open_position` | trading | Step 2 of 2: opens a real Papertrade position with the user's funds, signed by the delegated session key. |\n| `close_positions` | trading | Closes open positions at the market, signed by the session key. |\n| `cancel_intent` | trading | Cancels a submitted intent that is still queued (not yet executed). |\n| `get_intent_status` | public | Whether a submitted intent is still queued, has produced an open position, or is no longer pending. |\n\nFull inputs and annotations: [Tool reference](https://papertrade-ai.ninabrekkerese.workers.dev/docs/tools). Public tools also work over plain HTTPS:\n\n```bash\ncurl https://papertrade-ai.ninabrekkerese.workers.dev/api/v1/tools/get_markets\ncurl \"https://papertrade-ai.ninabrekkerese.workers.dev/api/v1/tools/get_liquidation_map?market=ETH\"\n```\n\nOpenAPI 3.1 at [`/openapi.json`](https://papertrade-ai.ninabrekkerese.workers.dev/openapi.json), ready for GPT Actions and agent frameworks. Unauthenticated MCP for read-only agents: `https://papertrade-ai.ninabrekkerese.workers.dev/public/mcp`.\n\n## Security\n\n- **Non-custodial.** Your wallet signs one EIP-712 `RegisterSessionKey` message, the same one the official Papertrade app signs for one-click trading. The session key is scoped by the exchange contract to open, close and cancel. It cannot withdraw or transfer.\n- **Guardrails in code, not in the prompt.** Margin per trade, leverage, rolling 24h position size, open positions and markets are checked on the server before any intent is signed.\n- **Preview, then confirm.** `open_position` needs a signed quote from `preview_trade` for the identical trade, valid for 3 minutes.\n- **Encrypted per app.** Each app's session key is encrypted with a key derived from that app's own access token.\n- **Revoke in one click** at [/account](https://papertrade-ai.ninabrekkerese.workers.dev/account).\n\nRead the full [security model](https://papertrade-ai.ninabrekkerese.workers.dev/docs/security). Report vulnerabilities privately: [SECURITY.md](SECURITY.md).\n\n## Develop and self-host\n\n```bash\ngit clone https://github.com/nirholas/papertrade-ai && cd papertrade-ai\nnpm install\nnpm test # unit tests\nnpm run dev # local Worker on http://127.0.0.1:8787\n```\n\nDeploy your own copy to Cloudflare Workers with one KV namespace and one secret: [Self-hosting](https://papertrade-ai.ninabrekkerese.workers.dev/docs/self-hosting). The package also exports the tool registry, policy engine and intent signing for use in your own agent: `import { TOOLS, runTool } from 'papertrade-ai'`.\n\n| Path | What |\n| --- | --- |\n| `src/tools/registry.ts` | Every tool: schema, annotations, implementation |\n| `src/core/` | Papertrade API client, EIP-712 intents, bust price math |\n| `src/worker/` | Cloudflare Worker: OAuth provider, MCP, REST, pages |\n| `src/cli.ts` | stdio server and `login` CLI |\n| `src/web/` | MCP Apps widget, connect and account pages |\n| `docs/` | Documentation (rendered to the website) |\n| `scripts/build-site.mjs` | Website, `llms.txt`, sitemap, discovery files, manifests |\n\n## Risk\n\nPapertrade positions use real USDC. At 1000x leverage a 0.1% move against you liquidates the position and the full margin is lost. Papertrade AI is independent open-source software, not affiliated with Papertrade, and not financial advice.\n\n## License\n\n[MIT](LICENSE)\n\n\n## Support the project\n\nIf papertrade-ai saves you time, **[star it on GitHub](https://github.com/nirholas/papertrade-ai)**. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.\n\nKnow someone who would use it? [Post on X](https://twitter.com/intent/tweet?text=papertrade-ai%3A%20Trade%20Papertrade%20BTC%20and%20ETH%20perps%20from%20Claude%2C%20ChatGPT%2C%20Codex%2C%20Cursor%2C%20Gemini%20CLI%20and%20VS%20Code&url=https%3A%2F%2Fgithub.com%2Fnirholas%2Fpapertrade-ai) · [Share on Bluesky](https://bsky.app/intent/compose?text=papertrade-ai%3A%20Trade%20Papertrade%20BTC%20and%20ETH%20perps%20from%20Claude%2C%20ChatGPT%2C%20Codex%2C%20Cursor%2C%20Gemini%20CLI%20and%20VS%20Code%20https%3A%2F%2Fgithub.com%2Fnirholas%2Fpapertrade-ai) · [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2Fnirholas%2Fpapertrade-ai) · [Submit to Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fgithub.com%2Fnirholas%2Fpapertrade-ai&t=papertrade-ai%3A%20Trade%20Papertrade%20BTC%20and%20ETH%20perps%20from%20Claude%2C%20ChatGPT%2C%20Codex%2C%20Cursor%2C%20Gemini%20CLI%20and%20VS%20Code) · [Share on Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fnirholas%2Fpapertrade-ai&title=papertrade-ai%3A%20Trade%20Papertrade%20BTC%20and%20ETH%20perps%20from%20Claude%2C%20ChatGPT%2C%20Codex%2C%20Cursor%2C%20Gemini%20CLI%20and%20VS%20Code)\n\n## Built for AI agents too\n\nCoding agents and LLM tooling can read this repo directly: [AGENTS.md](./AGENTS.md), [llms.txt](./llms.txt), [llms-full.txt](./llms-full.txt). Point an agent at `https://github.com/nirholas/papertrade-ai` and it has the context it needs.\n\n## More from the same author\n\n- [All repositories by nirholas](https://github.com/nirholas/nirholas#readme): the full catalog, grouped by topic\n- [three.ws](https://three.ws): the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments\n- Questions or ideas: [open an issue](https://github.com/nirholas/papertrade-ai/issues) or [start a discussion](https://github.com/nirholas/papertrade-ai/discussions)\n\n## Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=nirholas/papertrade-ai)](https://github.com/nirholas/papertrade-ai/graphs/contributors)\n\n## Star history\n\n[![Star History Chart](https://api.star-history.com/svg?repos=nirholas/papertrade-ai&type=Date)](https://www.star-history.com/#nirholas/papertrade-ai&Date)\n\n\n"}