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

# Tool reference

<!-- Generated by scripts/build-site.mjs from src/tools/registry.ts. Do not edit by hand. -->

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](rest-api.md) and the unauthenticated endpoint `https://papertrade-ai.ninabrekkerese.workers.dev/public/mcp`.

| Tool | What it does | Access |
| --- | --- | --- |
| [`get_markets`](#get_markets) | Markets | public |
| [`get_price_chart`](#get_price_chart) | Price chart | public |
| [`get_protocol_stats`](#get_protocol_stats) | Protocol stats | public |
| [`get_liquidation_map`](#get_liquidation_map) | Liquidation map | public |
| [`get_leaderboard`](#get_leaderboard) | Leaderboard | public |
| [`get_top_trades`](#get_top_trades) | Top trades | public |
| [`get_recent_trades`](#get_recent_trades) | Recent trades | public |
| [`get_account`](#get_account) | Account | public |
| [`get_trade_history`](#get_trade_history) | Trade history | public |
| [`get_portfolio_history`](#get_portfolio_history) | Portfolio history | public |
| [`calculate_position`](#calculate_position) | Position calculator | public |
| [`get_deposit_info`](#get_deposit_info) | Deposit instructions | public |
| [`get_trading_permissions`](#get_trading_permissions) | Trading permissions | public |
| [`preview_trade`](#preview_trade) | Preview trade | trading session |
| [`open_position`](#open_position) | Open position | trading session |
| [`close_positions`](#close_positions) | Close positions | trading session |
| [`cancel_intent`](#cancel_intent) | Cancel intent | trading session |
| [`get_intent_status`](#get_intent_status) | Intent status | public |

## 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `market` | `BTC`, `ETH` | yes |  | Market symbol: BTC or ETH. |
| `interval` | `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `3d`, `1w`, `1M` | no | `"15m"` | Candle interval. |
| `count` | integer 10 to 500 | no | `96` | Number of candles. |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `days` | integer 1 to 365 | no | `14` | Days of daily history to include. |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `market` | `BTC`, `ETH` | yes |  | Market symbol: BTC or ETH. |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `window` | `24h`, `7d`, `30d`, `all` | no | `"24h"` |  |
| `sortKey` | `rank`, `address`, `lastActiveTs`, `totalWindowedPnl`, `realizedPnl`, `currentUnrealizedPnl`, `currentBalance`, `currentQueued`, `currentOpenNotional`, `totalVolume`, `paperTotal`, `currentOpenPositionCount` | no | `"rank"` |  |
| `sortDir` | `asc`, `desc` | no | `"asc"` |  |
| `page` | integer 0 to 1000 | no | `0` | 0-based page; 25 rows per page. |
| `q` | string | no |  | Filter by leaderboard name or address. |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `window` | `24h`, `7d`, `30d`, `all` | no | `"24h"` |  |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `market` | `BTC`, `ETH` | no |  | Market symbol: BTC or ETH. |
| `wallet` | address | no |  |  |

## 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `wallet` | address | no |  | Wallet address (0x...). Defaults to the connected wallet. |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `wallet` | address | no |  | Wallet address (0x...). Defaults to the connected wallet. |
| `pages` | integer 1 to 10 | no | `1` | Pages of 75 trades. |

### get_portfolio_history

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

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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `wallet` | address | no |  | Wallet address (0x...). Defaults to the connected wallet. |
| `range` | `1h`, `1d`, `1w`, `all` | no | `"1d"` |  |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `wallet` | address | no |  | Wallet address (0x...). Defaults to the connected wallet. |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `market` | `BTC`, `ETH` | yes |  | Market symbol: BTC or ETH. |
| `side` | `long`, `short` | yes |  | long profits if price rises, short if it falls. |
| `marginUsd` | number > 0 | yes |  |  |
| `leverage` | integer 1 to 1000 | yes |  |  |
| `entryPrice` | number > 0 | no |  | Defaults to the live ask (long) or bid (short). |
| `exitPrice` | number > 0 | no |  | Target exit to evaluate. |

## 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `market` | `BTC`, `ETH` | yes |  | Market symbol: BTC or ETH. |
| `side` | `long`, `short` | yes |  | long profits if price rises, short if it falls. |
| `marginUsd` | number > 0 | yes |  | USD margin to commit (the most you can lose). |
| `leverage` | integer 1 to 1000 | yes |  |  |

### 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)

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `market` | `BTC`, `ETH` | yes |  | Market symbol: BTC or ETH. |
| `side` | `long`, `short` | yes |  | long profits if price rises, short if it falls. |
| `marginUsd` | number > 0 | yes |  |  |
| `leverage` | integer 1 to 1000 | yes |  |  |
| `quoteId` | string | no |  | From preview_trade. Required when the owner enabled confirmations (the default). |

### 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)

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `positionIds` | array of string | no |  |  |
| `all` | boolean | no |  | Close every open position (optionally only in `market`). |
| `market` | `BTC`, `ETH` | no |  | Market symbol: BTC or ETH. |

### cancel_intent

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

- Access: trading session
- Annotations: writes, idempotent

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `intentId` | string | yes |  |  |

### 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

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `intentId` | string | yes |  |  |
| `wallet` | address | no |  | Wallet address (0x...). Defaults to the connected wallet. |