paper-exchange MCP server
Commit Nov 11, 2026Lets AI agents simulate perpetual crypto trading with live Hyperliquid prices and fake money to test strategies without financial risk.
Also known as nirholas/paper-exchange
- Stars
- 5
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- Apache-2.0
What is paper-exchange MCP?
paper-exchange lets AI agents simulate perpetual crypto trading with live Hyperliquid prices and fake money to test strategies without financial risk. It exposes 8 tools, such as preview_order, place_order, close_position.
Summary generated from the project's README
About paper-exchange MCP server
Simulating perpetual cryptocurrency trading with live market prices and simulated funds is what paper-exchange enables for AI agents. Developers can connect clients like Claude, Cursor, or ChatGPT to a risk-free environment that uses real data from Hyperliquid to test trading strategies. Every new account starts with $10,000 of simulated USD, allowing agents to experience real liquidation, margin mechanics, and slippage without any financial consequences.
Users can run this as a local stdio server for single agents or as an HTTP server to manage multiple accounts simultaneously. The system provides specific tools for market analysis, such as list_markets and get_candles, alongside execution tools like place_order and preview_order. It also includes safety features like stop-loss and take-profit settings. Because the engine evaluates liquidations and stops in a continuous risk loop, it provides a faithful sandbox for benchmarking model performance on a public leaderboard before moving to real funds.
What you can do with it
- 1Benchmark model performanceDevelopers can rank different AI models against each other using live market data on a public leaderboard.
- 2Educate agents on market mechanicsAn AI can learn how margin, funding, and liquidations work in a controlled environment.
Written from the project's README. Every use case is checked against a quote from it.
paper-exchange MCP tools 8
Detected from the READMEpreview_orderplace_orderclose_positionset_protectionget_accountget_leaderboardreset_accountcreate_account
Automated checks
Ran Nov 14, 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/paper-exchange is public and reachablegithub.com/nirholas/paper-exchange ↗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/paper-exchange ↗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 model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubpaper-exchange
A paper-trading exchange for AI agents. Real market prices, fake money.
Connect Claude, ChatGPT, Cursor or any MCP client and your agent can trade perpetuals with leverage, limit orders, stop-loss and take-profit, and real liquidation, against live prices from Hyperliquid. Nothing touches a wallet. Every account starts with $10,000 of simulated USD, so an agent can be wrong, get liquidated, reset and try again at no cost.
Use it to:
- Test a trading agent's prompts and strategy before it goes near real funds.
- Benchmark models against each other on the same live market, ranked on a public leaderboard.
- Teach an agent a venue's mechanics (margin, funding of risk, liquidation) safely.
Apache-2.0. Node 22.13+. No API keys, no database server, no native dependencies.
Website
A hosted terminal lives at https://paper-exchange.pages.dev. It runs the same engine in your browser against live Hyperliquid data, with an analytics dashboard (funding heatmap, cross-venue funding, history), a portfolio journal and shareable PnL cards. Accounts are stored in your browser, so stops and liquidations are evaluated while a tab is open. For an agent that trades around the clock, run the MCP server yourself.
Quick start
git clone https://github.com/nirholas/paper-exchange && cd paper-exchange
npm install && npm run build
Claude Code (one local agent, auto-created account):
claude mcp add paper-exchange -- node /absolute/path/to/paper-exchange/dist/cli.js stdio
Claude Desktop, Cursor, any stdio client:
{
"mcpServers": {
"paper-exchange": {
"command": "node",
"args": ["/absolute/path/to/paper-exchange/dist/cli.js", "stdio"]
}
}
}
Then ask: "Preview a $2,000 SOL long at 10x with a 5% stop, and open it if the liquidation price is more than 8% away."
Many agents on one server (each gets its own account and key):
node dist/cli.js http --port 8787 # MCP at http://127.0.0.1:8787/mcp
An anonymous connection can call the market tools and create_account, which returns an API key once. Reconnect with Authorization: Bearer <key> to trade. GET /v1/leaderboard and GET /v1/markets are public JSON.
Tools
| Tool | What it does |
|---|---|
list_markets, get_price, get_candles |
Every perp market with max leverage and live price; OHLCV candles. |
preview_order |
Exact fill price, fee, margin, liquidation price and balance after. Places nothing. |
place_order |
Market or limit, with optional leverage, reduce-only, stop-loss and take-profit. |
close_position |
Close all or a fraction of a position at market. |
set_protection |
Set or clear stop-loss and take-profit on an open position. |
get_account |
Equity, available cash, positions (unrealized PnL, liquidation price, distance to it), resting orders. |
list_orders, cancel_order, get_trades |
Resting orders, cancellation with margin refund, fill history. |
get_leaderboard |
Public ranking by equity. |
reset_account |
Wipe everything back to the starting balance. |
create_account |
HTTP mode only. Returns the API key. |
Tool failures come back as readable errors that say how to fix them (insufficient_balance: Need $601.39, have $9,999.10. Lower sizeUsd or raise leverage.), so an agent can correct itself without a human.
How the simulation works
| Rule | Behavior |
|---|---|
| Prices | Live mids from Hyperliquid's public info API, cached for 1 second. If the source is down, orders fail loudly rather than fill at a stale price. |
| Fills | Mid moved against you by 2 bps flat slippage plus 1 bp per $50,000 of notional. Big orders cost more. |
| Fees | Taker 4.5 bps, maker 1.5 bps, charged on notional and shown in every preview. |
| Margin | Isolated per position. margin = notional / leverage, up to each market's real max leverage. |
| Liquidation | At entry * (1 - 1/leverage + 0.5%) for longs, mirrored for shorts. A 2-second risk loop checks every position. A liquidated position loses its margin, never more, so cash cannot go negative. |
| Limit orders | Marketable limits fill at once as taker. Others rest, holding their margin, and fill as maker at the limit price when the mid reaches it. |
| Netting | One position per market. Same side adds at a weighted entry price and keeps the original leverage. An opposite-side order reduces or closes it; an oversized one closes it. |
| Stops | Stop-loss and take-profit close at market through the same risk loop. |
| Accounting | equity = cash + margin + unrealized PnL + reserved order margin, and equity = starting balance + realized PnL + unrealized PnL always holds. |
Not modeled: funding payments, cross margin, order-book depth beyond the impact term, partial limit fills. The goal is faithful risk mechanics for agent evaluation, not a matching engine.
Configuration
| Variable | Default | Meaning |
|---|---|---|
PAPER_EXCHANGE_DATA |
~/.paper-exchange |
SQLite database and the stdio default key. |
PAPER_EXCHANGE_BALANCE |
10000 |
Starting balance for new accounts, USD. |
PAPER_EXCHANGE_API_KEY |
none | stdio only: act as an existing account. |
PORT, HOST |
8787, 127.0.0.1 |
HTTP bind. Set HOST=0.0.0.0 to expose it, and put TLS in front. |
Fees, slippage, maintenance margin and limits are fields of Config when embedding the engine.
Use as a library
import { Exchange, HyperliquidFeed, Store } from 'paper-exchange';
const ex = new Exchange(new Store('./paper.db'), new HyperliquidFeed());
const { account, apiKey } = ex.createAccount('my-agent');
const quote = await ex.quote(account.id, { market: 'BTC', side: 'long', sizeUsd: 5000, leverage: 10 });
await ex.placeOrder(account.id, { market: 'BTC', side: 'long', sizeUsd: 5000, leverage: 10, stopLoss: quote.fillPrice * 0.97 });
setInterval(() => ex.sweep(), 2000); // liquidations, stops, resting limit orders
Implement PriceFeed to drive it from any other source, or from recorded data to backtest an agent.
Development
npm test # 70 tests: engine, funding, book fills, risk, MCP protocol, HTTP auth
npm run build:site # bundle the website into site/public
npm run deploy:site # publish it to Cloudflare Pages (needs wrangler credentials in the environment)
npm run test:live # also checks the live price source
npm run typecheck && npm run build
Related
papertrade-ai is the MCP server for the real Papertrade exchange, where trades spend real funds. This project is the zero-risk sandbox: graduate an agent there once its paper results hold up.
Security
Accounts hold no real value. API keys are random 256-bit tokens stored only as SHA-256 hashes. Request bodies are capped at 256 KB. There is no rate limiting, so run a public deployment behind a gateway.
License
Apache-2.0. See LICENSE and NOTICE.
paper-exchange MCP questions
What tools does paper-exchange MCP provide?
It exposes 8 tools, including preview_order, place_order, close_position, set_protection, get_account.
Where do the market prices come from?
The server uses live mid-prices from the Hyperliquid public information API.
Can I use this to benchmark different AI models?
Yes, you can benchmark models against each other on the same live market using a public leaderboard.
How much starting balance does an account have?
Every new account is initialized with $10,000 of simulated USD.