MCP and REST API

AiyoPerps MCP and REST API handbook

This page documents the MCP tool names, parameter schemas, async operation rules, and REST API endpoints that AiyoPerps actually exposes. It is intended to be prompt-ready, so AI agents can use the correct tool names and argument fields without guessing.

Open MCP tool catalog Open REST API overview

Service model

Local endpoints and access rules

REST API base

http://127.0.0.1:5078/api/v1

The desktop UI can start or stop the local HTTP server. Headless or Docker mode starts it automatically.

MCP endpoint

http://127.0.0.1:5078/mcp

Uses JSON-RPC over HTTP and supports initialize, ping, tools/list, and tools/call.

OpenAPI UI

http://127.0.0.1:5078/scalar

Open it in a browser to inspect and test REST endpoints.

MCP schema REST endpoint

GET /api/v1/mcp/tools

Useful when external systems need to inspect the currently exposed MCP tool metadata.

Only local access is allowed. Valid hosts include 127.0.0.1, localhost, ::1, and winhost; on Windows the app also accepts detected WSL vEthernet subnets. Invalid local origins or non-local hosts receive 403.

Prompt rules

Rules to remember before putting AiyoPerps tools into prompts

Use underscore tool namesArguments accept camelCase or PascalCaseMutating tools require operations_get follow-upNever invent accountId or orderId

AiyoPerps MCP is the source of truth for live trading state and verified execution results.
New clients should use underscore tool names such as dashboard_status_get rather than legacy dotted names.
Read-only tools usually return data immediately; trading, cancel, and Dashboard control tools often return an async operation envelope first.
After tools such as dashboard_start, dashboard_refresh, positions_open, or orders_cancel, keep polling operations_get until the status becomes Succeeded or Failed.
If you only need one account's positions, orders, balances, or market data, prefer direct read tools like positions_list, orders_list, balances_list, and market_snapshot without starting Dashboard runtime unless you need integrated Dashboard context.

MCP catalog

MCP tool catalog

Accounts and symbols

accounts_list, accounts_get, accounts_create, accounts_update, accounts_delete, symbols_list

Connections and 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 and account reads

market_snapshot, market_data_get, positions_list, orders_list, balances_list

Trading and stress

dashboard_positions_open, dashboard_positions_close, dashboard_orders_cancel, positions_open, positions_close, orders_cancel, stress_run

System and async status

operations_get, app_shutdown

Accounts and symbols

Account and symbol tools

Tool	Purpose	Required arguments	Optional arguments
`accounts_list`	List all configured accounts. For portfolio-wide workflows, this is usually the first tool to call.	None	None
`accounts_get`	Read a single account profile.	`accountId`	None
`accounts_create`	Create a new account profile with credentials.	`venueId`, `displayName`, `environment`, `summary`	`authMode`, `apiKey`, `apiSecret`, `accountAddress`, `subAccountId`, `walletAddress`, `privateKey`, `isEnabled`
`accounts_update`	Update an existing account profile and credentials.	`accountId`, `venueId`, `displayName`, `environment`, `summary`	`authMode`, `apiKey`, `apiSecret`, `accountAddress`, `subAccountId`, `walletAddress`, `privateKey`, `isEnabled`
`accounts_delete`	Delete an account. This is asynchronous.	`accountId`	None
`symbols_list`	List tradable symbols for one account.	`accountId`	None

venueId supports BitMEX, Hyperliquid, Aster, GRVT, and dYdX. environment supports mainnet and testnet. authMode supports ApiKey, Wallet, and Both.

Dashboard and AI agent

Connections, Dashboard, and AI agent tools

Tool	Purpose	Required arguments	Optional arguments
`connections_list`	List active market-data backend sessions.	None	None
`connections_open`	Open a backend connection for one account and symbol. This is asynchronous.	`accountId`, `symbol`, `interval`	None
`connections_close`	Close a backend connection for one account and symbol. This is asynchronous.	`accountId`, `symbol`	None
`dashboard_status_get`	Read Dashboard runtime status and row counters.	None	None
`dashboard_options_get`	Read selectable accounts and symbols for the current Dashboard configuration.	None	None
`dashboard_config_get`	Read the current Dashboard configuration.	None	None
`dashboard_config_set`	Update the Dashboard configuration.	`selectedAccountIds`, `interval`, `showTestnet`	`symbol`
`dashboard_snapshot_get`	Read the latest Dashboard snapshot from runtime cache. It does not fetch fresh live state by itself.	None	None
`dashboard_start`	Start Dashboard runtime with the current configuration. This is asynchronous.	None	None
`dashboard_stop`	Stop Dashboard runtime and clear runtime data. This is asynchronous.	None	None
`dashboard_refresh`	Refresh the Dashboard snapshot immediately. This is asynchronous.	None	None
`ai_agent_settings_get`	Read the current AI agent scheduler settings.	None	None
`ai_agent_settings_set`	Replace AI agent scheduler settings, including timed and threshold-based wake rules.	`isEnabled`, `agentType`, `wakeIntervalMinutes`, `commandTemplate`, `promptTemplate`, `workingDirectory`, `timeoutSeconds`	`environmentVariables`, `wakeConditions[]`

dashboard_config_set fields

selectedAccountIds: selected account GUID array.
symbol: dashboard symbol such as BTC.
interval: candle interval, default 5m.
showTestnet: whether testnet accounts appear in the selection.

ai_agent_settings_set wake conditions

conditionId: optional stable identifier, auto-generated if omitted.
isEnabled: whether the condition is active.
accountId: optional account filter; omit to watch all enabled accounts.
symbol: the position symbol to watch.
metric: price or unrealizedPnlPct.
comparison: gt or lt.
threshold: numeric threshold value.

Market and account reads

Market data and account-state read tools

Tool	Purpose	Required arguments	Optional arguments
`market_snapshot`	Read initial candle snapshots or cursor-based deltas.	`accountId`, `symbol`	`interval`, `cursor`
`market_data_get`	Read market candle data with the same argument model as `market_snapshot`.	`accountId`, `symbol`	`interval`, `cursor`
`positions_list`	List active positions for one account.	`accountId`	`symbol`
`orders_list`	List open orders for one account.	`accountId`	`symbol`
`balances_list`	List balances for one account.	`accountId`	`symbol`

The cursor pattern for market_snapshot and market_data_get is: first call without cursor to receive initialCandles and a new cursor, then call again with that cursor to receive only deltaCandles and the next cursor.

Trading and operations

Trading, cancel, stress, and async status tools

Tool	Purpose	Required arguments	Optional arguments
`dashboard_positions_open`	Open or add exposure on a Dashboard account row. This is asynchronous.	`accountId`, `symbol`, `side`, `orderType`, `leverage`, `amount`, `amountUnit`	`marginMode`, `limitPrice`
`dashboard_positions_close`	Fully close a Dashboard position by `positionId`. This is asynchronous.	`accountId`, `positionId`, `orderType`	`limitPrice`
`dashboard_orders_cancel`	Cancel a Dashboard order. This is asynchronous.	`accountId`, `symbol`, `orderId`	None
`positions_open`	Open a position directly without Dashboard runtime. This is asynchronous.	`accountId`, `symbol`, `side`, `orderType`, `leverage`, `amount`, `amountUnit`	`marginMode`, `limitPrice`
`positions_close`	Close a position directly by `positionId`. This is asynchronous.	`accountId`, `positionId`, `orderType`	`limitPrice`
`orders_cancel`	Cancel an order directly without Dashboard runtime. This is asynchronous.	`accountId`, `symbol`, `orderId`	None
`stress_run`	Run the server-side market snapshot stress test.	`accountId`, `symbol`	`interval`, `concurrency`, `iterations`
`operations_get`	Read async operation status and result.	`operationId`	None
`app_shutdown`	Request graceful app shutdown and resource release.	None	None

Trading enums

side: buy, sell, long, short
orderType: market, limit
marginMode: cross, isolated
amountUnit: for example USD or the base asset symbol

Async operation rules

Common statuses: Pending, Running, Succeeded, Failed
Mutating tools usually return operationId and statusUrl first.
Keep polling operations_get until the operation finishes.
For Dashboard flows, refresh and re-read the snapshot after a successful mutation to verify the final result.

REST quick reference

REST API overview

Endpoint	Method	Purpose	Main arguments
`/api/v1/health`	GET	Service health check	None
`/api/v1/app/shutdown`	POST	Request graceful app shutdown	None
`/api/v1/dashboard/status`, `/options`, `/config`, `/snapshot`	GET	Read Dashboard status, options, config, and snapshot	None
`/api/v1/dashboard/config`	PUT	Update Dashboard config	`selectedAccountIds`, `interval`, `showTestnet`, optional `symbol`
`/api/v1/dashboard/start`, `/stop`, `/refresh`	POST	Control Dashboard runtime	None
`/api/v1/dashboard/open-position`, `/close-position`, `/cancel-order`	POST	Mutate positions and orders through Dashboard runtime	Same body schema as the matching trading action
`/api/v1/ai-agent/settings`	GET / PUT	Read or update AI agent settings	Same shape as `ai_agent_settings_set`
`/api/v1/accounts`, `/api/v1/accounts/{accountId}`	GET / POST / PUT / DELETE	Account CRUD	`accountId` and `ApiAccountUpsertRequest`
`/api/v1/accounts/{accountId}/symbols`, `/api/v1/symbols?accountId=...`	GET	Symbol list	`accountId`
`/api/v1/connections`, `/open`, `/close`	GET / POST	Manage market-data connections	`accountId`, `symbol`, optional `interval`
`/api/v1/market-data`, `/api/v1/market/snapshot`	GET	Market candle data	`accountId`, `symbol`, optional `interval`, `cursor`
`/api/v1/positions`, `/api/v1/orders`, `/api/v1/balances`	GET	Account-state reads	`accountId`, optional `symbol`
`/api/v1/trading/open-position`, `/close-position`, `/cancel-order`	POST	Direct trading operations	Same body schema as the matching MCP trading action
`/api/v1/stress/run`	POST	Stress test	`accountId`, `symbol`, optional `interval`, `concurrency`, `iterations`
`/api/v1/operations/{operationId}`	GET	Query async operation state	`operationId`

Prompt examples

Prompt examples you can adapt directly

Read-only analysis prompt

Please call accounts_list first, then for each returned accountId call positions_list, orders_list, and balances_list.
Do not execute any trades or cancel any orders.
Summarize current exposure, open orders, and available balances for each account, and use market_snapshot on BTC only if extra market context is needed.

Dashboard workflow prompt

Use dashboard_status_get to inspect runtime first.
If it is not running, call dashboard_options_get, then use dashboard_config_set with the selected account, symbol BTC, and interval 5m, then call dashboard_start.
After that, read dashboard_snapshot_get and summarize markets, positions, and open orders without placing any trade.

Execution prompt

Use positions_open to place one market long on BTC for the specified accountId.
Provide leverage, amount, and amountUnit explicitly.
After submission, keep polling operations_get until the result is Succeeded or Failed.
If successful, verify the final state with positions_list and orders_list.

AI wake-rule prompt

Read ai_agent_settings_get first.
Then update the current configuration with ai_agent_settings_set, keeping the existing commandTemplate and workingDirectory,
and add one wakeCondition that watches BTC on the specified accountId using unrealizedPnlPct with comparison lt and threshold -8.
Return the full updated settings payload at the end.

Need MCP installed first?

If you have not yet registered AiyoPerps MCP in Codex or another host, finish the AI agent setup guide first.

Open AI agent setup guide

Need the local service running first?

If you plan to expose MCP or REST API from a headless node, finish the Docker headless workflow first.

Open Docker headless guide