AiyoPerps logoOfficial WebsiteAiyoPerps
MCP and REST API

AiyoPerps MCP 及 REST API 工具手冊

這頁整理 AiyoPerps 實際支援的 MCP tool 名稱、參數 schema、非同步操作規則與 REST API 端點。你可以把這些名稱直接放進 prompt，讓 AI Agent 用正確的 tool 名稱與參數格式操作 AiyoPerps。

直接看 MCP 工具表 看 REST API 快覽
Service model

本機服務端點與存取規則

REST API Base

http://127.0.0.1:5078/api/v1

桌面版可由上方工具列啟動或停止，headless / Docker 模式會自動啟動。

MCP Endpoint

http://127.0.0.1:5078/mcp

使用 JSON-RPC over HTTP，支援 initialize、ping、tools/list、tools/call。

OpenAPI UI

http://127.0.0.1:5078/scalar

可直接在瀏覽器查看 REST API 文件與測試端點。

MCP Tool Schema REST

GET /api/v1/mcp/tools

若你要在外部系統做自動同步，可以讀這個端點取得目前公開的 MCP 工具資訊。

只允許本機連線。合法 host 包含 127.0.0.1、localhost、::1、winhost；Windows 也允許偵測到的 WSL vEthernet 子網段。非本機來源或不合法 Origin 會收到 403。

Prompt rules

把 AiyoPerps 工具寫進 Prompt 前，先記住這幾條

Tool 名稱一律用底線 參數接受 camelCase / PascalCase 修改型工具要再查 operations_get 不要猜 accountId / symbol / orderId
  • AiyoPerps MCP 是即時交易狀態與執行結果的事實來源。若 prompt 有外部報告或網路資訊，agent 應先讀背景，再回到 AiyoPerps 驗證 live state。
  • 新的 client 應使用底線名稱，例如 dashboard_status_get，不要再用舊的句點名稱。
  • 讀取型工具通常可以直接呼叫；交易、取消單、Dashboard 啟停等修改型工具大多先回傳非同步 operation envelope。
  • 呼叫 dashboard_start、dashboard_refresh、positions_open、orders_cancel 這類工具後，應再用 operations_get 輪詢直到狀態是 Succeeded 或 Failed。
  • 如果只需要查單一帳號的持倉、掛單、餘額或市場資料，優先使用 direct read tools，例如 positions_list、orders_list、balances_list、market_snapshot，不一定要先 dashboard_start。
MCP catalog

MCP 工具總覽

帳號與商品

accounts_list、accounts_get、accounts_create、accounts_update、accounts_delete、symbols_list

Connections 與 Dashboard

connections_list、connections_open、connections_close、dashboard_status_get、dashboard_options_get、dashboard_config_get、dashboard_config_set、dashboard_snapshot_get、dashboard_start、dashboard_stop、dashboard_refresh

AI Agent

ai_agent_settings_get、ai_agent_settings_set

市場與帳戶讀取

market_snapshot、market_data_get、positions_list、orders_list、balances_list

交易與壓測

dashboard_positions_open、dashboard_positions_close、dashboard_orders_cancel、positions_open、positions_close、orders_cancel、stress_run

系統與非同步查詢

operations_get、app_shutdown

Accounts and symbols

帳號與商品工具

Tool 用途 必填參數 可選參數
accounts_list 列出所有已設定帳號。做 portfolio-wide workflow 時通常先從這裡開始。 無 無
accounts_get 讀取單一帳號資料。 accountId：帳號 GUID。 無
accounts_create 建立新的帳號設定與憑證。 venueId、displayName、environment、summary authMode、apiKey、apiSecret、accountAddress、subAccountId、walletAddress、privateKey、isEnabled
accounts_update 更新既有帳號資料與憑證。 accountId、venueId、displayName、environment、summary authMode、apiKey、apiSecret、accountAddress、subAccountId、walletAddress、privateKey、isEnabled
accounts_delete 刪除帳號。這是非同步操作。 accountId 無
symbols_list 列出指定帳號可交易商品。 accountId 無

venueId 支援 BitMEX、Hyperliquid、Aster、GRVT、dYdX。environment 支援 mainnet 與 testnet。authMode 支援 ApiKey、Wallet、Both。

Dashboard and AI agent

Dashboard、Connections 與 AI Agent 工具

Tool 用途 必填參數 可選參數
connections_list 列出目前 active 的 market-data backend session。 無 無
connections_open 開啟指定帳號與商品的後端連線。這是非同步操作。 accountId、symbol、interval 無
connections_close 關閉指定帳號與商品的後端連線。這是非同步操作。 accountId、symbol 無
dashboard_status_get 讀取 Dashboard runtime 狀態與 counters。 無 無
dashboard_options_get 讀取目前 Dashboard 可選帳號與 symbol。 無 無
dashboard_config_get 讀取目前 Dashboard 設定。 無 無
dashboard_config_set 更新 Dashboard 設定。 selectedAccountIds、interval、showTestnet symbol
dashboard_snapshot_get 讀取最新 Dashboard snapshot。這是 runtime cache，不會自己重新抓 live state。 無 無
dashboard_start 依目前設定啟動 Dashboard runtime。這是非同步操作。 無 無
dashboard_stop 停止 Dashboard runtime 並清空 runtime data。這是非同步操作。 無 無
dashboard_refresh 立即刷新 Dashboard snapshot。這是非同步操作。 無 無
ai_agent_settings_get 讀取目前 AI Agent scheduler 設定。 無 無
ai_agent_settings_set 覆蓋 AI Agent scheduler 設定，可設定定時喚醒與條件喚醒。 isEnabled、agentType、wakeIntervalMinutes、commandTemplate、promptTemplate、workingDirectory、timeoutSeconds environmentVariables、wakeConditions[]
dashboard_config_set 參數補充
  • selectedAccountIds：已選帳號 GUID 陣列。
  • symbol：目前 Dashboard 商品，例如 BTC。
  • interval：K 線週期，預設 5m。
  • showTestnet：是否包含 testnet 帳號。
ai_agent_settings_set 的 wakeConditions[]
  • conditionId：可省略，系統會自動產生。
  • isEnabled：是否啟用該條件。
  • accountId：可省略，表示監看所有啟用帳號。
  • symbol：監看的商品。
  • metric：price 或 unrealizedPnlPct。
  • comparison：gt 或 lt。
  • threshold：門檻值。
Market and account reads

市場資料與帳戶狀態讀取工具

Tool 用途 必填參數 可選參數
market_snapshot 讀取初始 candle snapshot 或根據 cursor 讀增量資料。 accountId、symbol interval、cursor
market_data_get 讀取市場 candle 資料；參數模型與 market_snapshot 相同。 accountId、symbol interval、cursor
positions_list 列出某帳號目前持倉。 accountId symbol
orders_list 列出某帳號目前 open orders。 accountId symbol
balances_list 列出某帳號餘額。 accountId symbol

market_snapshot / market_data_get 的 cursor 模式是: 第一次不帶 cursor，回傳 initialCandles 與新 cursor；後續再帶入 cursor，只回傳 deltaCandles 與新的 cursor。

Trading and operations

交易、取消單、壓測與非同步查詢工具

Tool 用途 必填參數 可選參數
dashboard_positions_open 在 Dashboard 選定帳號列上開倉或增加曝險。這是非同步操作。 accountId、symbol、side、orderType、leverage、amount、amountUnit marginMode、limitPrice
dashboard_positions_close 在 Dashboard 上依 positionId 全平持倉。這是非同步操作。 accountId、positionId、orderType limitPrice
dashboard_orders_cancel 取消 Dashboard 中的掛單。這是非同步操作。 accountId、symbol、orderId 無
positions_open 直接開倉，不依賴 Dashboard runtime。這是非同步操作。 accountId、symbol、side、orderType、leverage、amount、amountUnit marginMode、limitPrice
positions_close 直接依 positionId 平倉，不依賴 Dashboard runtime。這是非同步操作。 accountId、positionId、orderType limitPrice
orders_cancel 直接取消掛單，不依賴 Dashboard runtime。這是非同步操作。 accountId、symbol、orderId 無
stress_run 執行 server-side market snapshot 壓測。 accountId、symbol interval、concurrency、iterations
operations_get 查詢非同步 operation 狀態與結果。 operationId 無
app_shutdown 請求 app 優雅關閉並釋放資源。 無 無
交易參數列舉值
  • side：buy、sell、long、short
  • orderType：market、limit
  • marginMode：cross、isolated
  • amountUnit：例如 USD 或標的幣別
非同步操作規則
  • 常見狀態：Pending、Running、Succeeded、Failed
  • 修改型 tool 成功送出後，通常先拿到 operationId 與 statusUrl
  • 應持續呼叫 operations_get 直到完成
  • 若是 Dashboard 流程，完成後通常還要再 dashboard_refresh 並重讀 snapshot 驗證結果
REST quick reference

REST API 快覽

Endpoint 方法 用途 主要參數
/api/v1/health GET 服務健康檢查 無
/api/v1/app/shutdown POST 請求 app 優雅關閉 無
/api/v1/dashboard/status、/options、/config、/snapshot GET 讀取 Dashboard 狀態、選項、設定與 snapshot 無
/api/v1/dashboard/config PUT 更新 Dashboard 設定 selectedAccountIds、interval、showTestnet、可選 symbol
/api/v1/dashboard/start、/stop、/refresh POST 控制 Dashboard runtime 無
/api/v1/dashboard/open-position、/close-position、/cancel-order POST 透過 Dashboard runtime 下單、平倉、取消單 同對應交易 body schema
/api/v1/ai-agent/settings GET / PUT 讀取或更新 AI Agent 設定 同 ai_agent_settings_set
/api/v1/accounts、/api/v1/accounts/{accountId} GET / POST / PUT / DELETE 帳號 CRUD accountId 與 ApiAccountUpsertRequest
/api/v1/accounts/{accountId}/symbols、/api/v1/symbols?accountId=... GET 商品列表 accountId
/api/v1/connections、/open、/close GET / POST 管理市場資料連線 accountId、symbol、可選 interval
/api/v1/market-data、/api/v1/market/snapshot GET 市場 candle 資料 accountId、symbol、可選 interval、cursor
/api/v1/positions、/api/v1/orders、/api/v1/balances GET 帳戶狀態查詢 accountId、可選 symbol
/api/v1/trading/open-position、/close-position、/cancel-order POST 直接交易操作 同對應交易 body schema
/api/v1/stress/run POST 壓測 accountId、symbol、可選 interval、concurrency、iterations
/api/v1/operations/{operationId} GET 查詢非同步 operation operationId
Prompt examples

可直接調整後使用的 Prompt 範例

唯讀分析 prompt
請先用 accounts_list 列出所有帳號，再對每個 accountId 呼叫 positions_list、orders_list、balances_list。 不要執行任何交易或取消單。 最後整理目前各帳號的持倉方向、未成交掛單與可用餘額，若需要市場資料再用 market_snapshot 讀取 BTC。
Dashboard workflow prompt
請先用 dashboard_status_get 檢查 runtime。 若尚未啟動，先用 dashboard_options_get 確認可用帳號與 symbol，再用 dashboard_config_set 將 selectedAccountIds 設為指定帳號、symbol 設為 BTC、interval 設為 5m，然後呼叫 dashboard_start。 之後讀取 dashboard_snapshot_get 回報市場、持倉與掛單摘要，不要下單。
執行交易 prompt
請使用 positions_open 在指定 accountId 對 BTC 開一筆 market long。 參數請明確帶入 leverage、amount、amountUnit。 送出後務必輪詢 operations_get，直到狀態為 Succeeded 或 Failed。 若成功，再用 positions_list 與 orders_list 驗證最新狀態。
設定 AI Agent 喚醒條件 prompt
請先讀 ai_agent_settings_get。 接著用 ai_agent_settings_set 更新目前設定，保留既有 commandTemplate 與 workingDirectory， 新增一筆 wakeCondition：監看指定 accountId 的 BTC，metric 使用 unrealizedPnlPct，comparison 使用 lt，threshold 設為 -8。 完成後回報新的設定內容。

需要先把 MCP 接進 Agent？

如果你還沒完成 Codex 或其他 AI Agent 的 MCP 安裝，先看安裝與互動指引會比較順。

前往 AI Agent 安裝指引

需要先開服務？

如果你要用 headless 節點對外提供 MCP / REST API，請先完成 Docker headless 啟動流程。

前往 Docker headless 教學