@michaleffffff/mcp-trading-server 3.0.3 → 3.0.5

package/TOOL_EXAMPLES.md

@@ -1,53 +1,14 @@
-# MYX MCP Tool Examples Handbook
+# MYX MCP Tool Examples Handbook (v3.0.4)
 
-This handbook is designed for AI assistants and integrators.
-It includes:
-- clear parameter unit rules,
-- common end-to-end workflows,
-- at least one practical call example for every exposed tool.
-
-> All examples use MCP call payload shape:
-> `{ "name": "<tool_name>", "arguments": { ... } }`
-
----
-
-## 1) Parameter Units & Precision (Important)
-
-- **Human-readable by default** (many trading tools): `"100"` means 100 quote tokens (e.g., USDC).
-- **Raw-unit override**: use `"raw:<integer>"` when supported by the tool.
-- **Price precision**: many low-level trading paths expect **30-decimal raw price**.
-- **Token amount precision**: depends on token decimals (e.g., USDC often 6).
-- **Slippage (`slippagePct`)**: 4-decimal integer style (e.g., `100 = 1%`, `50 = 0.5%`).
-- **Approval tool** (`check_approval`) uses **raw integer amount**.
+This guide provides practical payload examples for the consolidated toolset. 
+All examples follow the MCP format: `{ "name": "...", "arguments": { ... } }`.
 
 ---
 
-## 2) Common Operation Flows
+## 🟢 Trading Operations
 
-## Flow A: Discover Market → Open Position (Recommended)
-1. `search_market` (keyword or empty keyword list)
-2. `get_market_detail` / `get_market_price`
-3. `get_account` (with `poolId`)
-4. `open_position_simple` (preferred high-level execution)
-
-## Flow B: Limit Order Lifecycle
-1. `execute_trade` with `orderType=LIMIT`
-2. `get_open_orders`
-3. `get_order_history`
-4. `cancel_order` or `cancel_all_orders`
-
-## Flow C: Balance Troubleshooting
-1. `get_account` (without `poolId`) → wallet view
-2. `get_account` (with `poolId`) → trading-account + margin
-3. `account_deposit` / `account_withdraw` as needed
-
----
-
-## 3) Tool-by-Tool Practical Examples
-
-## Trading Operations
-
-### `open_position_simple`
+### `open_position_simple` (Recommended)
+High-level tool that computes size and fees automatically.
 ```json
 {
   "name": "open_position_simple",
@@ -55,575 +16,122 @@ It includes:
     "keyword": "BTC",
     "direction": "LONG",
     "collateralAmount": "100",
-    "leverage": 5,
-    "orderType": "MARKET",
-    "autoDeposit": false,
-    "dryRun": true
+    "leverage": 10,
+    "tpPrice": "75000",
+    "slPrice": "62000"
   }
 }
 ```
 
-### `execute_trade`
+### `cancel_orders` (Unified)
+Supports three modes: single ID, all in a pool, or all in account.
 ```json
+// Mode 1: Specific IDs
 {
-  "name": "execute_trade",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "positionId": "",
-    "orderType": "MARKET",
-    "direction": "LONG",
-    "collateralAmount": "100",
-    "size": "0.01",
-    "price": "65000",
-    "timeInForce": 0,
-    "postOnly": false,
-    "slippagePct": "100",
-    "executionFeeToken": "0xQUOTE_TOKEN",
-    "leverage": 5,
-    "marketId": "0xMARKET_ID"
-  }
-}
-```
-Notes:
-- `tradingFee` is optional (auto-computed if omitted).
-- Amount-like fields support `human:` and `raw:` prefixes.
-- `positionId: "0x000...000"` is auto-treated as a new position.
-
-### `close_position`
-```json
-{
-  "name": "close_position",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "positionId": "0xPOSITION_ID",
-    "orderType": "MARKET",
-    "direction": "LONG",
-    "collateralAmount": "0",
-    "size": "0.01",
-    "price": "65000",
-    "timeInForce": 0,
-    "postOnly": false,
-    "slippagePct": "100",
-    "executionFeeToken": "0xQUOTE_TOKEN",
-    "leverage": 5
-  }
-}
-```
-
-### `close_all_positions`
-```json
-{
-  "name": "close_all_positions",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "slippagePct": "200"
-  }
+  "name": "cancel_orders",
+  "arguments": { "orderIds": ["0x123...", "0x456..."] }
 }
-```
 
-### `cancel_order`
-```json
+// Mode 2: Pool-wide
 {
-  "name": "cancel_order",
-  "arguments": {
-    "orderId": "0xORDER_ID"
-  }
+  "name": "cancel_orders",
+  "arguments": { "poolId": "BTC" }
 }
-```
 
-### `cancel_all_orders`
-```json
+// Mode 3: Global
 {
-  "name": "cancel_all_orders",
-  "arguments": {
-    "orderIds": [
-      "0xORDER_ID_1",
-      "0xORDER_ID_2"
-    ]
-  }
-}
-```
-Single-ID string is also accepted:
-```json
-{
-  "name": "cancel_all_orders",
-  "arguments": {
-    "orderIds": "0xORDER_ID_1"
-  }
+  "name": "cancel_orders",
+  "arguments": { "cancelAll": true }
 }
 ```
 
-### `set_tp_sl`
+### `manage_tp_sl`
+Update existing protection orders or set new ones for a position.
 ```json
 {
-  "name": "set_tp_sl",
+  "name": "manage_tp_sl",
   "arguments": {
-    "poolId": "0xPOOL_ID",
-    "positionId": "0xPOSITION_ID",
-    "direction": "LONG",
+    "poolId": "BTC",
+    "positionId": "0xABC...",
     "leverage": 5,
-    "executionFeeToken": "0xQUOTE_TOKEN",
-    "tpTriggerType": "GTE",
-    "tpPrice": "70000",
-    "tpSize": "0.01",
-    "slTriggerType": "LTE",
-    "slPrice": "60000",
-    "slSize": "0.01",
-    "slippagePct": "100"
-  }
-}
-```
-
-### `update_order_tp_sl`
-```json
-{
-  "name": "update_order_tp_sl",
-  "arguments": {
-    "orderId": "0xORDER_ID",
-    "marketId": "0xMARKET_ID",
-    "size": "0.01",
-    "price": "65000",
-    "tpPrice": "70000",
-    "tpSize": "0.005",
-    "slPrice": "60000",
-    "slSize": "0.005",
-    "useOrderCollateral": true,
-    "quoteToken": "0xQUOTE_TOKEN"
-  }
-}
-```
-String booleans are also accepted:
-```json
-{
-  "name": "update_order_tp_sl",
-  "arguments": {
-    "orderId": "0xORDER_ID",
-    "marketId": "0xMARKET_ID",
-    "size": 0.01,
-    "price": 65000,
-    "tpPrice": 70000,
-    "tpSize": 0.005,
-    "slPrice": 60000,
-    "slSize": 0.005,
-    "useOrderCollateral": "true",
-    "isTpSlOrder": "true",
-    "quoteToken": "0xQUOTE_TOKEN"
-  }
-}
-```
-Note:
-- This tool is most reliable for existing TP/SL orders or open positions.
-- If an unfilled LIMIT/STOP order returns `Failed to update order`, wait for fill and use `set_tp_sl`.
-
-### `adjust_margin`
-```json
-{
-  "name": "adjust_margin",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "positionId": "0xPOSITION_ID",
-    "adjustAmount": "1"
-  }
-}
-```
-Raw precision mode:
-```json
-{
-  "name": "adjust_margin",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "positionId": "0xPOSITION_ID",
-    "adjustAmount": "raw:1000000"
-  }
-}
-```
-Success payload includes normalized raw amount under `data.normalized.adjustAmountRaw`.
-
-### `check_approval`
-```json
-{
-  "name": "check_approval",
-  "arguments": {
-    "amount": "100000000",
-    "autoApprove": false
-  }
-}
-```
-
-### `get_user_trading_fee_rate`
-```json
-{
-  "name": "get_user_trading_fee_rate",
-  "arguments": {
-    "assetClass": 1,
-    "riskTier": 1
-  }
-}
-```
-
-### `get_network_fee`
-```json
-{
-  "name": "get_network_fee",
-  "arguments": {
-    "marketId": "0xMARKET_ID"
-  }
-}
-```
-
-## Market Data
-
-### `search_market`
-```json
-{
-  "name": "search_market",
-  "arguments": {
-    "keyword": "ETH",
-    "limit": 10
-  }
-}
-```
-
-### `search_market` (list active markets)
-```json
-{
-  "name": "search_market",
-  "arguments": {
-    "keyword": "",
-    "limit": 20
-  }
-}
-```
-Note: this tool may internally fallback to SDK `api.getMarketList()` / `api.getPoolList()` when direct search is empty.
-
-### `get_pool_list`
-```json
-{
-  "name": "get_pool_list",
-  "arguments": {}
-}
-```
-
-### `get_market_detail`
-```json
-{
-  "name": "get_market_detail",
-  "arguments": {
-    "poolId": "BTC"
-  }
-}
-```
-
-### `get_pool_info`
-```json
-{
-  "name": "get_pool_info",
-  "arguments": {
-    "poolId": "0xPOOL_ID"
-  }
-}
-```
-Note: the server auto-retries with oracle/ticker market price when direct on-chain read hits divide-by-zero.
-
-### `get_liquidity_info`
-```json
-{
-  "name": "get_liquidity_info",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "marketPrice": "6500000000000000000000000000000000"
-  }
-}
-```
-
-### `get_pool_level_config`
-```json
-{
-  "name": "get_pool_level_config",
-  "arguments": {
-    "poolId": "0xPOOL_ID"
-  }
-}
-```
-
-### `get_market_price`
-```json
-{
-  "name": "get_market_price",
-  "arguments": {
-    "poolId": "0xPOOL_ID"
-  }
-}
-```
-
-### `get_oracle_price`
-```json
-{
-  "name": "get_oracle_price",
-  "arguments": {
-    "poolId": "0xPOOL_ID"
-  }
-}
-```
-
-### `get_kline`
-```json
-{
-  "name": "get_kline",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "interval": "15m",
-    "limit": 100
-  }
-}
-```
-
-### `get_kline_latest_bar`
-```json
-{
-  "name": "get_kline_latest_bar",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "interval": "1m"
-  }
-}
-```
-
-### `get_all_tickers`
-```json
-{
-  "name": "get_all_tickers",
-  "arguments": {}
-}
-```
-
-### `get_pool_symbol_all`
-```json
-{
-  "name": "get_pool_symbol_all",
-  "arguments": {}
-}
-```
-
-### `get_base_detail`
-```json
-{
-  "name": "get_base_detail",
-  "arguments": {
-    "baseAddress": "0xBASE_TOKEN"
-  }
-}
-```
-
-## Account & Query
-
-### `get_account`
-```json
-{
-  "name": "get_account",
-  "arguments": {
-    "poolId": "0xPOOL_ID"
-  }
-}
-```
-
-If one section fails, check `data.meta.partial` and section-level `error` fields.
-
-### `get_account` (wallet-only view)
-```json
-{
-  "name": "get_account",
-  "arguments": {}
-}
-```
-
-### `get_my_lp_holdings`
-```json
-{
-  "name": "get_my_lp_holdings",
-  "arguments": {}
-}
-```
-LP asset naming rule in each item:
-- `baseLpAssetName`: `mBASE.QUOTE` (e.g. `mBTC.USDC`)
-- `quoteLpAssetName`: `mQUOTE.BASE` (e.g. `mUSDC.BTC`)
-Include zero-balance pools and optional filtering:
-```json
-{
-  "name": "get_my_lp_holdings",
-  "arguments": {
-    "includeZero": true,
-    "poolIds": [
-      "0xPOOL_ID_1",
-      "0xPOOL_ID_2"
-    ],
-    "maxPools": 50
+    "tpPrice": "80000",
+    "slPrice": "55000"
   }
 }
 ```
 
-### `get_positions`
-```json
-{
-  "name": "get_positions",
-  "arguments": {}
-}
-```
-
-### `get_open_orders`
-```json
-{
-  "name": "get_open_orders",
-  "arguments": {}
-}
-```
+---
 
-### `get_order_history`
-```json
-{
-  "name": "get_order_history",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "limit": 20
-  }
-}
-```
+## 🔵 Market Data
 
-### `get_position_history`
+### `find_pool`
+Keyword or symbol based discovery.
 ```json
 {
-  "name": "get_position_history",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "limit": 20
-  }
+  "name": "find_pool",
+  "arguments": { "keyword": "ETH" }
 }
 ```
 
-### `get_trade_flow`
+### `get_price`
+Unified price fetching.
 ```json
 {
-  "name": "get_trade_flow",
-  "arguments": {
-    "limit": 20
+  "name": "get_price",
+  "arguments": { 
+    "poolId": "0x...", 
+    "priceType": "market" 
   }
 }
 ```
 
-### `get_account_vip_info`
+### `get_pool_metadata`
+Detailed pool state (Fees, Liquidity, Open Interest).
 ```json
 {
-  "name": "get_account_vip_info",
-  "arguments": {}
-}
-```
-
-### `account_deposit`
-```json
-{
-  "name": "account_deposit",
-  "arguments": {
-    "amount": "100",
-    "tokenAddress": "0xQUOTE_TOKEN"
-  }
+  "name": "get_pool_metadata",
+  "arguments": { "poolId": "0x..." }
 }
 ```
 
-### `account_withdraw`
-```json
-{
-  "name": "account_withdraw",
-  "arguments": {
-    "poolId": "0xPOOL_ID",
-    "amount": "50",
-    "isQuoteToken": true
-  }
-}
-```
+---
 
-## Liquidity / LP
+## 🟡 Account & Portfolio
 
-### `manage_liquidity`
+### `get_account_snapshot`
+Unified overview. Includes wallet balances and VIP info.
 ```json
 {
-  "name": "manage_liquidity",
-  "arguments": {
-    "action": "deposit",
-    "poolType": "QUOTE",
-    "poolId": "0xPOOL_ID",
-    "amount": 100,
-    "slippage": 0.01
-  }
-}
-```
-Alias action example (`remove` == `withdraw`):
-```json
-{
-  "name": "manage_liquidity",
-  "arguments": {
-    "action": "remove",
-    "poolType": "BASE",
-    "poolId": "0xPOOL_ID",
-    "amount": 1.5,
-    "slippage": 0.01
-  }
-}
-```
-If operation fails, check `error.message` for concrete reasons (for example `Insufficient Balance`) instead of generic `undefined`.
-`poolId` must be valid on the target `chainId`; if uncertain, resolve with `search_market` / `get_pool_list` first.
-Success response includes `data.lpAssetNames`:
-- `baseLpAssetName`: `mBASE.QUOTE` (e.g. `mBTC.USDC`)
-- `quoteLpAssetName`: `mQUOTE.BASE` (e.g. `mUSDC.BTC`)
-- `operatedLpAssetName`: LP asset name matching current `poolType`
-Example success payload (abridged):
-```json
-{
-  "status": "success",
-  "data": {
-    "confirmation": {
-      "confirmed": true,
-      "txHash": "0x..."
-    },
-    "lpAssetNames": {
-      "baseSymbol": "BTC",
-      "quoteSymbol": "USDC",
-      "baseLpAssetName": "mBTC.USDC",
-      "quoteLpAssetName": "mUSDC.BTC",
-      "operatedPoolType": "QUOTE",
-      "operatedLpAssetName": "mUSDC.BTC"
-    }
-  }
+  "name": "get_account_snapshot",
+  "arguments": { "poolId": "BTC" }
 }
 ```
 
-### `get_lp_price`
+### `get_orders`
+Unified list for both active (OPEN) and historical (HISTORY) orders.
 ```json
 {
-  "name": "get_lp_price",
-  "arguments": {
-    "poolType": "QUOTE",
-    "poolId": "0xPOOL_ID"
+  "name": "get_orders",
+  "arguments": { 
+    "status": "ALL",
+    "limit": 10
   }
 }
 ```
 
-### `create_perp_market`
+### `get_positions_all`
+Current open positions and closed history.
 ```json
 {
-  "name": "create_perp_market",
-  "arguments": {
-    "baseToken": "0xBASE_TOKEN",
-    "marketId": "0xMARKET_CONFIG_HASH"
-  }
+  "name": "get_positions_all",
+  "arguments": { "status": "OPEN" }
 }
 ```
 
 ---
 
-## 4) Practical Tips for AI Agents
+## 💡 Important Rules
 
-- Always discover/validate `poolId` before mutation tools.
-- Prefer `open_position_simple` for new-position UX unless strict low-level control is required.
-- Before trading, call `get_account` and `check_approval`.
-- For limit-order support conversations, include `get_open_orders` and `get_order_history` in the loop.
-- If any mutation fails, read structured error fields: `error.code`, `error.hint`, `error.action`.
+1. **Unit Prefixing**: Use `human:` for readable amounts and `raw:` for exact on-chain units. Default is usually human-readable for high-level tools.
+2. **Pool Discovery**: Always run `find_pool` first to get the correct `poolId`.
+3. **Pre-trade Check**: Use `check_account_ready` to ensure enough collateral is in the trading account before opening positions.