Tool reference

Every Papertrade AI tool with its inputs, access level and safety annotations. Markets, charts, liquidation maps, leaderboards, wallet analytics, previews and guarded trading.

Papertrade AI exposes 18 tools. Every tool returns a one-line summary the model can relay and a structured data object. Public tools also work over the REST API and the unauthenticated endpoint https://papertrade-ai.ninabrekkerese.workers.dev/public/mcp.

Markets and analytics#

No wallet needed.

get_markets#

Markets. 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. Call this before trading.

• Access: public
• Annotations: read-only, idempotent

No inputs.

get_price_chart#

Price chart. OHLCV candles for BTC or ETH from Hyperliquid (the price source Papertrade settles against), with range stats and a TradingView link.

• Access: public
• Annotations: read-only, idempotent

get_protocol_stats#

Protocol stats. Papertrade protocol analytics: TVL, margin, LP, lifetime volume, open positions, fees, PAPER supply and staking, plus daily history (volume, trader PnL, liquidations, users).

• Access: public
• Annotations: read-only, idempotent

get_liquidation_map#

Liquidation map. 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.

• Access: public
• Annotations: read-only, idempotent

get_leaderboard#

Leaderboard. Papertrade trader leaderboard for a time window, sortable by PnL, volume, balance and more. Search by name or address with q.

• Access: public
• Annotations: read-only, idempotent

get_top_trades#

Top trades. The most profitable individual Papertrade positions in a window: who, market, side, leverage, entry, exit and PnL.

• Access: public
• Annotations: read-only, idempotent

get_recent_trades#

Recent trades. The latest opens, closes and liquidations across all of Papertrade, optionally filtered by market or wallet.

• Access: public
• Annotations: read-only, idempotent

Accounts#

Any wallet by address, or the connected wallet by default.

get_account#

Account. 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. Any wallet can be inspected.

• Access: public
• Annotations: read-only, idempotent

get_trade_history#

Trade history. Closed and liquidated positions for a wallet, newest first, with entry, exit, settled PnL, fees and PAPER minted.

• Access: public
• Annotations: read-only, idempotent

get_portfolio_history#

Portfolio history. Equity curve for a wallet over 1h, 1d, 1w or all time.

• Access: public
• Annotations: read-only, idempotent

get_deposit_info#

Deposit instructions. 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. Read-only; it never moves funds.

• Access: public
• Annotations: read-only, idempotent

get_trading_permissions#

Trading permissions. 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.

• Access: public
• Annotations: read-only, idempotent

No inputs.

Planning#

Pure math with live prices.

calculate_position#

Position calculator. 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). Does not need a wallet.

• Access: public
• Annotations: read-only, idempotent

Trading#

Previewing, opening, closing and cancelling need a trading session approved by the wallet owner, with guardrails enforced on the server. Intent status is public.

preview_trade#

Preview trade. Step 1 of 2 for opening a position. Checks the trade against exchange limits, the account balance and the owner guardrails, estimates entry, bust price and PnL scenarios, and returns a quoteId valid for 3 minutes. Show the preview to the user and get an explicit yes before calling open_position with the quoteId.

• Access: trading session
• Annotations: read-only, idempotent

open_position#

Open position. Step 2 of 2: opens a real Papertrade position with the user's funds, signed by the delegated session key. Requires the quoteId from preview_trade for the identical market, side, margin and leverage, and only after the user explicitly confirmed. Waits for settlement and reports the fill.

• Access: trading session
• Annotations: writes, destructive (clients ask before running)

close_positions#

Close positions. Closes open positions at the market, signed by the session key. Pass positionIds, or all=true optionally narrowed by market. Confirm with the user before closing. Reports each settled result.

• Access: trading session
• Annotations: writes, destructive (clients ask before running)

cancel_intent#

Cancel intent. Cancels a submitted intent that is still queued (not yet executed).

• Access: trading session
• Annotations: writes, idempotent

get_intent_status#

Intent status. Whether a submitted intent is still queued, has produced an open position, or is no longer pending.

• Access: public
• Annotations: read-only, idempotent