Papertrade AI

io.github.nirholasPublished by GitHub account nirholasv0.1.0Updated Oct 24, 2026

Trade Papertrade BTC and ETH perps from Claude, ChatGPT, Codex, Cursor and any MCP client.

VerifiedStreamable HTTPWeb executableFinanceData & Analytics

Overview

AI-generated overview

MCP server for Papertrade BTC and ETH perpetual futures: live market data, wallet analytics, liquidation maps, and guarded trade execution via a session key.

What you can do
  • Read live BTC/ETH perp markets, OHLCV price charts and protocol stats
  • Inspect liquidation maps, leaderboards, top and recent trades
  • Review a wallet's account, open positions, trade history and equity curve
  • Calculate hypothetical position math such as bust price and liquidation distance
  • Preview, open, close and cancel trades, and check intent status
  • Get deposit instructions and current trading permissions and limits
When to use it
Useful when you want an assistant to research Papertrade perp markets, analyze wallets and liquidation levels, or place and manage small leveraged BTC/ETH positions under server-enforced limits. Read-only use works without any wallet connection.
Requirements
Remote streamable HTTP endpoint with OAuth 2.1, or the npm package papertrade-ai run locally via npx with Node.js. A wallet is needed for account and trading tools; the optional PAPERTRADE_PRIVATE_KEY enables headless trading, and PAPERTRADE_WALLET allows read-only access without logging in. Local credentials are stored in the user's config directory.
Before you install
Trades use real USDC and can be lost entirely; at high leverage a small adverse move liquidates the position. Trading tools open and close real positions with your funds, so review every preview before confirming. The optional PAPERTRADE_PRIVATE_KEY is a wallet key and should be treated as highly sensitive. The project is independent and not affiliated with Papertrade, and its output is not financial advice.

Installation

In SourceWeft

  1. Open Papertrade AI in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.nirholas%2Fpapertrade-ai/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "papertrade-ai": {
      "type": "http",
      "url": "https://papertrade-ai.ninabrekkerese.workers.dev/mcp"
    }
  }
}

README

[Papertrade AI: trade perps from any AI. Claude, ChatGPT, Codex, Cursor, Gemini, VS Code.]

Papertrade AI

Trade Papertrade BTC and ETH perps from Claude, ChatGPT, Codex, Cursor, Gemini CLI, VS Code and any MCP client.

Open-source Model Context Protocol server with live markets, wallet analytics, liquidation maps, and guarded trading through non-custodial session keys.

[npm] [MCP Registry] [License: MIT] [Docs]

[Add to Cursor] [Install in VS Code]

Website · Docs · Tools · Security · REST API

https://papertrade-ai.ninabrekkerese.workers.dev/mcp

One 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.

What you can ask

  • "What are BTC and ETH doing on Papertrade right now?"
  • "Show me the Papertrade liquidation map for ETH."
  • "Who are the top 10 Papertrade traders this week? What are they holding?"
  • "Analyze wallet 0x...: win rate, biggest trade, equity curve."
  • "If I long BTC with $20 at 500x, where is my liquidation price?"
  • "Preview a $15 ETH short at 800x, then open it if I confirm."
  • "Close all my BTC positions."

On clients with MCP Apps support (Claude, ChatGPT, VS Code, Goose) results render as an interactive trading card with a live chart.

Install

ClientInstall
Claude (web, desktop, mobile)Settings, Connectors, Add custom connector, paste https://papertrade-ai.ninabrekkerese.workers.dev/mcp. Guide
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
ChatGPTSettings, Apps, Advanced settings, Developer mode, Create app, paste the URL, OAuth. Guide
OpenAI Codexcodex mcp add papertrade --url https://papertrade-ai.ninabrekkerese.workers.dev/mcp then codex mcp login papertrade Guide
CursorOne-click install Guide
VS Code (Copilot)One-click install or code --add-mcp '{"name":"papertrade","type":"http","url":"https://papertrade-ai.ninabrekkerese.workers.dev/mcp"}' Guide
Gemini CLIgemini extensions install https://github.com/nirholas/papertrade-ai Guide
Claude Desktop (local)Download papertrade-ai.mcpb from Releases and open it.
Windsurf, Zed, Cline, Goose, LibreChat, othersStreamable HTTP URL above, or stdio npx -y papertrade-ai. Guide

Local (stdio)

json
{  "mcpServers": {    "papertrade": { "command": "npx", "args": ["-y", "papertrade-ai"] }  }}

Run npx -y papertrade-ai login once to connect a wallet in your browser. Credentials stay in ~/.config/papertrade-ai (mode 0600). CLI guide

Tools

ToolAccessWhat it does
get_marketspublicLive 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.
get_price_chartpublicOHLCV candles for BTC or ETH from Hyperliquid (the price source Papertrade settles against), with range stats and a TradingView link.
get_protocol_statspublicPapertrade protocol analytics: TVL, margin, LP, lifetime volume, open positions, fees, PAPER supply and staking, plus daily history (volume, trader PnL, liquidations, users).
get_liquidation_mappublicWhere open Papertrade positions get liquidated: notional and position count of longs and shorts by price bucket around the current price, with the largest clusters.
get_leaderboardpublicPapertrade trader leaderboard for a time window, sortable by PnL, volume, balance and more.
get_top_tradespublicThe most profitable individual Papertrade positions in a window: who, market, side, leverage, entry, exit and PnL.
get_recent_tradespublicThe latest opens, closes and liquidations across all of Papertrade, optionally filtered by market or wallet.
get_accountpublicA 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.
get_trade_historypublicClosed and liquidated positions for a wallet, newest first, with entry, exit, settled PnL, fees and PAPER minted.
get_portfolio_historypublicEquity curve for a wallet over 1h, 1d, 1w or all time.
calculate_positionpublicPure 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).
get_deposit_infopublicHow 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.
get_trading_permissionspublicWhat 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.
preview_tradetradingStep 1 of 2 for opening a position.
open_positiontradingStep 2 of 2: opens a real Papertrade position with the user's funds, signed by the delegated session key.
close_positionstradingCloses open positions at the market, signed by the session key.
cancel_intenttradingCancels a submitted intent that is still queued (not yet executed).
get_intent_statuspublicWhether a submitted intent is still queued, has produced an open position, or is no longer pending.

Full inputs and annotations: Tool reference. Public tools also work over plain HTTPS:

bash
curl https://papertrade-ai.ninabrekkerese.workers.dev/api/v1/tools/get_marketscurl "https://papertrade-ai.ninabrekkerese.workers.dev/api/v1/tools/get_liquidation_map?market=ETH"

OpenAPI 3.1 at /openapi.json, ready for GPT Actions and agent frameworks. Unauthenticated MCP for read-only agents: https://papertrade-ai.ninabrekkerese.workers.dev/public/mcp.

Security

  • 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.
  • 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.
  • Preview, then confirm. open_position needs a signed quote from preview_trade for the identical trade, valid for 3 minutes.
  • Encrypted per app. Each app's session key is encrypted with a key derived from that app's own access token.
  • Revoke in one click at /account.

Read the full security model. Report vulnerabilities privately: SECURITY.md.

Develop and self-host

bash
git clone https://github.com/nirholas/papertrade-ai && cd papertrade-ainpm installnpm test           # unit testsnpm run dev        # local Worker on http://127.0.0.1:8787

Deploy your own copy to Cloudflare Workers with one KV namespace and one secret: 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'.

PathWhat
src/tools/registry.tsEvery tool: schema, annotations, implementation
src/core/Papertrade API client, EIP-712 intents, bust price math
src/worker/Cloudflare Worker: OAuth provider, MCP, REST, pages
src/cli.tsstdio server and login CLI
src/web/MCP Apps widget, connect and account pages
docs/Documentation (rendered to the website)
scripts/build-site.mjsWebsite, llms.txt, sitemap, discovery files, manifests

Risk

Papertrade 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.

License

MIT

Support the project

If papertrade-ai saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/papertrade-ai and it has the context it needs.

More from the same author

Contributors

[Contributors]

Star history

[Star History Chart]

Source: README.md at commit d4554bb

Tools

0
SourceWeft has not read this server's tools yet.

Version history

1
  1. v0.1.0LatestOct 10, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts