{
  "markdown": "# mcp-pear\n\n[![npm](https://img.shields.io/npm/v/@marvelcodes/mcp-pear.svg)](https://www.npmjs.com/package/@marvelcodes/mcp-pear)\n[![CI](https://github.com/MarvelNwachukwu/mcp-pear/actions/workflows/push.yml/badge.svg)](https://github.com/MarvelNwachukwu/mcp-pear/actions)\n\n**The Pear Protocol MCP server for Hyperliquid pair trading** — connect Claude, Cursor, or any AI agent to on-chain perps: browse pair markets, read positions and portfolio, and (opt-in) execute pair trades.\n\nModel Context Protocol (MCP) server for [Pear Protocol](https://pearprotocol.io). Gives Claude, or any MCP-compatible agent, access to markets, pair ratios, positions, orders, trade history, portfolio, and (v0.2) full trade execution on Hyperliquid.\n\n> **v0.2 adds trade execution.** Ten write tools (open, close, and adjust positions; manage leverage and risk; cancel orders) are off by default behind `PEAR_TRADE_ENABLED=true`. Pear signs server-side, so mcp-pear never holds private keys.\n\n## What is Pear Protocol?\n\nPear is a Hyperliquid-backed perps platform for **pair markets**: long one basket against another. Every pair has a live ratio that moves as the legs diverge. More at [pearprotocol.io](https://pearprotocol.io).\n\n## Tools\n\nPublic (no auth):\n\n- `get_health`: API health and uptime\n- `list_markets`: browse pair markets with filters and pagination\n- `get_active_markets`: top gainers, losers, and highlighted pairs\n- `get_pair_ratio`: current ratio, 24h change, and funding for a specific pair\n\nAuthenticated read:\n\n- `get_account_summary`: your account header\n- `get_open_positions`: your open positions with PnL\n- `get_open_orders`: your open limit, TP, and SL orders\n- `get_twap_orders`: your active TWAP orders\n- `get_trade_history`: your closed trades with realized PnL\n- `get_portfolio`: bucketed PnL across 1d, 1w, 1m, 1y, and all-time\n- `get_agent_wallet`: the agent wallet Pear uses to sign your trades\n\nAuthenticated write (v0.2, gated behind `PEAR_TRADE_ENABLED=true`):\n\n- `create_agent_wallet`: create the agent wallet\n- `open_position`, `close_position`, `close_all_positions`: open and close pair positions\n- `adjust_position`, `adjust_leverage`: change size or leverage on a live position\n- `set_risk_parameters`: set or update TP and SL\n- `cancel_order`, `cancel_twap_order`: cancel pending orders\n\nFull parameter reference in [Tool reference](#tool-reference). See [Trade execution (v0.2)](#trade-execution-v02) for the gate and Hyperliquid funding rules.\n\n## Install\n\n```bash\n# Run directly\nnpx -y @marvelcodes/mcp-pear@latest\n\n# Or install globally\npnpm install -g @marvelcodes/mcp-pear\nmcp-pear\n```\n\n> **Pin `@latest` (or a specific version) in the npx spec.** Plain `npx @marvelcodes/mcp-pear` can launch a stale cached version: npx prefers its local cache over the npm registry when the spec is unpinned, so after a new release lands you may still be running the old one. `@latest` re-resolves against the registry each launch; pin like `@0.2.0` instead if you want a frozen version. Stuck on an old version after upgrading? Clear the npx cache: `rm -rf ~/.npm/_npx` (macOS/Linux).\n\n## Getting an API key\n\nFor the authenticated tools, mint a key:\n\n```bash\nnpx -y @marvelcodes/mcp-pear@latest setup\n```\n\nThe CLI opens a browser, asks you to sign once with your wallet, mints a Pear API key, and (optionally) writes `PEAR_API_KEY` and `PEAR_ADDRESS` to a `.env`. Copy those two values into your Claude Desktop config and restart Claude.\n\n> Already have a JWT from `app.pear.garden`? Skip `setup` and use **JWT pass-through** below.\n\n## Configuration\n\nThree auth modes. mcp-pear uses the first one whose env vars are set, decided on the first authenticated call.\n\n### Mode 1: JWT pass-through (multi-tenant orchestrators)\n\nFor Telegram bots and other orchestrators that mint JWTs externally (Privy, EIP-712, or any Pear-supported flow). The JWT is opaque; mcp-pear never calls `/auth/login`.\n\n| Env var | Required | Description |\n|---|---|---|\n| `PEAR_JWT` | yes | Pre-minted access token. Used directly when set. `PEAR_API_KEY` and `PEAR_ADDRESS` act as fallback if the JWT expires and no `PEAR_REFRESH_TOKEN` is configured. |\n| `PEAR_REFRESH_TOKEN` | no | If set, mcp-pear refreshes the JWT itself when it expires mid-session (each refresh rotates the token). Without it, the orchestrator has to re-mint and respawn the subprocess. |\n\nWhen `PEAR_JWT` expires and no refresh token is set, authenticated tools return:\n\n> `JWT expired; the orchestrator must mint a new one and restart mcp-pear.`\n\nSee [`examples/telegram-bot-usage.ts`](./examples/telegram-bot-usage.ts) for the orchestrator pattern.\n\n### Mode 2: API key + wallet address (single-user, Claude Desktop)\n\n| Env var | Required | Description |\n|---|---|---|\n| `PEAR_API_KEY` | for auth tools | Your Pear API key. |\n| `PEAR_ADDRESS` | for auth tools | Wallet address bound to the API key (`0x...`). |\n\nmcp-pear mints the JWT itself by calling `POST /auth/login`. Both fields are required: the OpenAPI spec needs `address` in the request body.\n\n### Public-only mode\n\nThe four public tools work without any auth env vars. Authenticated tools return a `ConfigError` naming the missing env var.\n\n### Common settings (optional)\n\n| Env var | Default | Description |\n|---|---|---|\n| `PEAR_API_BASE_URL` | `https://hl-v2.pearprotocol.io` | Pear API host. |\n| `PEAR_API_TIMEOUT_MS` | `10000` | Per-request timeout. |\n| `PEAR_CLIENT_ID` | `APITRADER` | Client identifier sent to `/auth/login`. |\n\n## Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pear\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@marvelcodes/mcp-pear@latest\"],\n      \"env\": {\n        \"PEAR_API_KEY\": \"your-pear-api-key-here\",\n        \"PEAR_ADDRESS\": \"0xYourWalletAddress\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop and ask: \"Use Pear to show me the top active markets right now.\"\n\n## ADK-TS\n\n```ts\nimport { McpToolset, StdioTransport } from \"@iqai/adk\";\n\nconst pearTools = new McpToolset({\n\ttransport: new StdioTransport({\n\t\tcommand: \"npx\",\n\t\targs: [\"-y\", \"@marvelcodes/mcp-pear@latest\"],\n\t\tenv: { PEAR_API_KEY: process.env.PEAR_API_KEY ?? \"\", PEAR_ADDRESS: process.env.PEAR_ADDRESS ?? \"\" },\n\t}),\n});\n\nawait pearTools.connect();\nconst tools = await pearTools.listTools();\n```\n\nFull example in [`examples/adk-ts-usage.ts`](./examples/adk-ts-usage.ts).\n\n## Tool reference\n\n<!-- AUTO-GENERATED TOOLS START -->\n\n### `adjust_leverage`\nChange leverage (1-100x) on an existing Pear Protocol position. Higher leverage means greater liquidation risk for the same price move. WRITE: changes risk profile of a live position. Requires PEAR_TRADE_ENABLED=true.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `positionId` | string | yes |  |\n| `leverage` | integer | yes |  |\n\n### `adjust_position`\nReduce or increase an existing Pear Protocol position's size by 1-100 percent. executionType: MARKET (immediate) or LIMIT (provide limitRatio). WRITE: changes exposure on a real trade. Requires PEAR_TRADE_ENABLED=true.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `positionId` | string | yes |  |\n| `adjustmentType` | string | yes |  |\n| `adjustmentSize` | integer | yes |  |\n| `executionType` | string | yes |  |\n| `limitRatio` | number |  |  |\n| `referralCode` | string |  |  |\n\n### `cancel_order`\nCancel a pending Pear Protocol limit, take-profit, or stop-loss order by orderId. Does not affect already-filled portions. For TWAP orders, use cancel_twap_order. WRITE: cancels a live order. Requires PEAR_TRADE_ENABLED=true.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `orderId` | string | yes |  |\n\n### `cancel_twap_order`\nCancel a Pear Protocol TWAP (time-weighted average price) order and all of its remaining unfilled chunks. WRITE: cancels a live order. Requires PEAR_TRADE_ENABLED=true.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `orderId` | string | yes |  |\n\n### `close_all_positions`\nClose every open Pear Protocol position with a single executionType (MARKET or TWAP). Returns a per-position result array with success/error. WRITE: executes real trades. Requires PEAR_TRADE_ENABLED=true.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `executionType` | string | yes |  |\n| `twapDuration` | number |  |  |\n| `twapIntervalSeconds` | number |  |  |\n| `randomizeExecution` | boolean |  |  |\n| `referralCode` | string |  |  |\n\n### `close_position`\nClose one open Pear Protocol position by positionId. executionType: MARKET (immediate) or TWAP (spread over time; requires twapDuration in seconds). WRITE: executes a real trade. Requires PEAR_TRADE_ENABLED=true.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `positionId` | string | yes |  |\n| `executionType` | string | yes |  |\n| `twapDuration` | number |  |  |\n| `twapIntervalSeconds` | number |  |  |\n| `randomizeExecution` | boolean |  |  |\n| `referralCode` | string |  |  |\n\n### `create_agent_wallet`\nCreate a new Pear Protocol agent wallet for the authenticated user. The agent wallet is what Pear uses to sign Hyperliquid trades. After creation, the user MUST approve this wallet on Hyperliquid (the response message contains the approval instructions). WRITE: executes a state change. Requires PEAR_TRADE_ENABLED=true.\n\n_No parameters_\n\n### `get_account_summary`\nGet the authenticated user's Pear Protocol account summary: agent wallet address, total closed trades, pending trigger-order USD value, pending TWAP-chunk USD value, and last sync timestamp. Requires PEAR_API_KEY.\n\n_No parameters_\n\n### `get_active_markets`\nGet the most active Pear Protocol pair markets right now: current active pairs plus top gainers, top losers, highlighted pairs, and the user's watchlist. Use to see what's hot or as a starting point for narrowing into a specific pair.\n\n_No parameters_\n\n### `get_agent_wallet`\nGet the authenticated user's Pear Protocol agent wallet address. The agent wallet is what Pear uses to sign Hyperliquid trades on the user's behalf. Returns an empty/missing address if no agent wallet has been created yet; call create_agent_wallet to create one.\n\n_No parameters_\n\n### `get_health`\nCheck Pear Protocol API health. Returns service status, server timestamp, and uptime in seconds. Use this to verify the API is reachable before running other tools.\n\n_No parameters_\n\n### `get_open_orders`\nList the authenticated user's open limit, take-profit, and stop-loss orders on Pear Protocol. Returns each order's ID, type, status, and pair composition. Requires PEAR_API_KEY.\n\n_No parameters_\n\n### `get_open_positions`\nList the authenticated user's currently open Pear Protocol pair positions, including position ID, entry ratio, mark ratio, unrealized PnL, and long/short composition. Requires PEAR_API_KEY.\n\n_No parameters_\n\n### `get_pair_ratio`\nGet the current ratio (long/short composition price) for a specific Pear Protocol pair. Pass long and short asset arrays. Returns the ratio, 24h change, and funding rate. Useful when you know the pair you care about and want the latest number.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `longAssets` | array | yes | Asset symbols on the long side (e.g. ['BTC']). |\n| `shortAssets` | array | yes | Asset symbols on the short side. Pass an empty array for long-only baskets. |\n\n### `get_portfolio`\nFetch the authenticated user's full portfolio metrics on Pear Protocol: bucketed PnL across last 1 day / 1 week / 1 month / 1 year / all-time, plus overall stats (total trades, all-time volume, current open interest, unrealized PnL). Requires PEAR_API_KEY.\n\n_No parameters_\n\n### `get_trade_history`\nFetch the authenticated user's recent closed trades on Pear Protocol with realized PnL, entry/exit ratios, and pair composition. Optional date range and limit. Requires PEAR_API_KEY.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `limit` | integer |  | Max number of trades to return. Default 50. |\n| `startDate` | string |  | ISO 8601 timestamp or epoch ms. Only return trades on or after this time. |\n| `endDate` | string |  | ISO 8601 timestamp or epoch ms. Only return trades on or before this time. |\n\n### `get_twap_orders`\nList the authenticated user's active TWAP (time-weighted average price) orders on Pear Protocol, including chunk execution and fill detail. Requires PEAR_API_KEY.\n\n_No parameters_\n\n### `list_markets`\nBrowse Pear Protocol pair markets with optional filters and pagination. Each market is a long/short composition with current ratio, 24h change, volume, open interest, and funding. Use to discover what's tradable, or with searchText to find a specific pair.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `search` | string |  | Free-text search across market names (composition keys like `L:BTC|S:ETH`). |\n| `engine` | string |  | Filter by execution engine. |\n| `minVolume` | number |  | Minimum 24h volume in USD. |\n| `change24h` | number |  | Minimum 24h ratio change (e.g. 0.05 for +5%). |\n| `netFunding` | number |  | Filter by net funding rate. |\n| `sort` | string |  | Sort key (e.g. 'volume', 'change24h'). |\n| `page` | integer |  | Page number (1-indexed). |\n| `pageSize` | integer |  | Results per page. Default 20. |\n\n### `open_position`\nOpen a new pair position on Pear Protocol. Specify executionType (MARKET / TRIGGER / TWAP / LADDER / TP / SL / SYNC), leverage (1-100), usdValue (≥1), slippage (0.001-0.1), and the long/short asset compositions (arrays of { asset, weight }). Optionally attach stopLoss/takeProfit and TWAP/TRIGGER/LADDER parameters. WRITE: executes a real trade. Requires PEAR_TRADE_ENABLED=true.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `executionType` | string | yes |  |\n| `leverage` | integer | yes |  |\n| `usdValue` | number | yes |  |\n| `slippage` | number | yes |  |\n| `longAssets` | array | yes |  |\n| `shortAssets` | array | yes |  |\n| `triggerValue` | number |  |  |\n| `triggerType` | string |  |  |\n| `direction` | string |  |  |\n| `twapDuration` | number |  |  |\n| `twapIntervalSeconds` | number |  |  |\n| `randomizeExecution` | boolean |  |  |\n| `ladderConfig` | object |  |  |\n| `stopLoss` | unknown |  |  |\n| `takeProfit` | unknown |  |  |\n| `referralCode` | string |  |  |\n\n### `set_risk_parameters`\nSet or update stop-loss / take-profit on an existing Pear Protocol position. Each threshold has type ('PRICE' or 'PERCENTAGE'), value, and optional trailing fields. Pass null to clear a field; omit it to leave unchanged. WRITE: changes risk parameters on a live position. Requires PEAR_TRADE_ENABLED=true.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `positionId` | string | yes |  |\n| `stopLoss` | unknown |  |  |\n| `takeProfit` | unknown |  |  |\n\n<!-- AUTO-GENERATED TOOLS END -->\n\n## Development\n\n```bash\npnpm install\npnpm run build\npnpm test\npnpm run lint\npnpm run format\n```\n\nLive smoke tests:\n\n```bash\nPEAR_API_KEY=<real> pnpm test smoke\n```\n\n## Trade execution (v0.2)\n\nTen new tools that take mcp-pear from read-only to write. **All write tools are off by default.** Set `PEAR_TRADE_ENABLED=true` to unlock them (strict literal match on `\"true\"`; anything else, including `\"True\"`, `\"1\"`, or `\"yes\"`, keeps writes disabled). Pear signs trades server-side via an agent wallet you create, so mcp-pear never holds private keys for trades.\n\n| Tool | Type | Description |\n|---|---|---|\n| `get_agent_wallet`     | read  | Get the agent wallet Pear uses to sign your trades. |\n| `create_agent_wallet`  | write | Create one. After creation, approve it on Hyperliquid (the response message contains the instructions). |\n| `open_position`        | write | Open a pair position. Supports MARKET, TRIGGER, TWAP, LADDER, TP, SL, SYNC. |\n| `close_position`       | write | Close one position by id (MARKET or TWAP). |\n| `close_all_positions`  | write | Close every open position with one execution type. |\n| `adjust_position`      | write | Reduce or increase position size by 1 to 100 percent. MARKET or LIMIT. |\n| `adjust_leverage`      | write | Set leverage 1 to 100x on an existing position. Carries liquidation risk. |\n| `set_risk_parameters`  | write | Set or update TP and SL on an existing position. |\n| `cancel_order`         | write | Cancel a pending limit, TP, or SL order. |\n| `cancel_twap_order`    | write | Cancel a TWAP order and its remaining chunks. |\n\n| Env var | Default | Description |\n|---|---|---|\n| `PEAR_TRADE_ENABLED` | unset | Set to `\"true\"` (lowercase, exact) to unlock the write tools. Anything else keeps them disabled and the gate error is returned to the LLM. |\n\nWhen `PEAR_TRADE_ENABLED=true`, mcp-pear logs `[mcp-pear] PEAR_TRADE_ENABLED=true. Trade execution unlocked.` to stderr on startup so operators can see writes are live.\n\n### Funding and minimums\n\nTrades execute on Hyperliquid, which margins positions from your **Perps** balance. Two things bite first-time operators:\n\n- **Minimum order size.** Hyperliquid rejects orders below ~$10 notional. `usdValue` is the position's USD notional (margin = `usdValue / leverage`), so a single-leg position needs `usdValue` at or above 10. A long plus short pair is two separate orders, each subject to the $10 floor (about $20 or more notional total).\n- **Spot vs Perps balance.** USDC bridged onto Hyperliquid (for example via Circle CCTP) often lands in your **Spot** balance. Move it to **Perps** in the Hyperliquid app before trading, or `open_position` fails with insufficient margin.\n\n## What's next\n\n**v0.3.** WebSocket streaming for real-time market and position updates. Spot orders. Candle synthesis from Hyperliquid `candleSnapshot`.\n\n## FAQ\n\n**What is the Pear Protocol MCP server?**\n`mcp-pear` is a Model Context Protocol (MCP) server that gives Claude and other AI agents access to [Pear Protocol](https://pearprotocol.io) — a Hyperliquid-backed platform for **pair trading** (long one basket against another). It exposes tools to browse pair markets and ratios, read positions, orders, and portfolio, and optionally execute pair trades.\n\n**How do I build a Pear Protocol trading agent?**\nPoint any MCP client at `npx -y @marvelcodes/mcp-pear@latest`. The agent gets read tools out of the box (markets, ratios, positions, portfolio). To let it trade, set `PEAR_TRADE_ENABLED=true` and add `PEAR_API_KEY` + `PEAR_ADDRESS`; it can then call `open_position` (MARKET / TRIGGER / TWAP / LADDER), `close_position`, `adjust_leverage`, and `set_risk_parameters`. See [Claude Desktop](#claude-desktop) and [ADK-TS](#adk-ts) for wiring examples.\n\n**Does it support Hyperliquid pair trading?**\nYes. Pear runs on Hyperliquid, so every pair position is a long/short perp trade executed on Hyperliquid. `mcp-pear` covers the full lifecycle: open, adjust, set TP/SL, and close.\n\n**Is this the official Pear Protocol MCP server?**\nNo. `mcp-pear` is an independent, open-source community project that wraps Pear's public API. It is not affiliated with or endorsed by Pear Protocol.\n\n## Disclaimer\n\nNot affiliated with Pear Protocol. Independent wrapper around Pear's public API. v0.2 trade-execution tools are off by default and require explicit operator opt-in (`PEAR_TRADE_ENABLED=true`). Pear signs server-side, so mcp-pear never holds private keys. Use at your own risk; no warranty.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n",
  "bytes": 19613,
  "sha": "f64ecea851f4df33a6ab0b5b10b2aff4b0bd2c0559b6ac18854460f75ca7d4b8",
  "repo_slug": "marvelnwachukwu/mcp-pear",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_marvelnwachukwu_mcp_pear_2657c068/readme"
}