Trade a simulated account with MCP

This quickstart is for a simulated or paper-backed prop account. Its orders go through the platform OMS and paper matching engine; no exchange wallet or agent private key is required. A live funded prop account uses different custody and authorization.

1. Get an API key for the account

   A paper account’s API key, its tier and its risk caps are decided by your workspace operator, not by the trader. Ask the operator to issue a key for the account in the admin console (Account → API keys). The tier they choose determines the tools the agent can use. They may also record a maximum position notional and daily-loss cap, which are passed on to the risk engine rather than enforced by TRON. The secret is shown once, at issue.

   Configure @tronchartsxyz/mcp-server version 0.2.0 or later over stdio in Claude Code, Cursor or Cline with that key and secret. There is no TRON_CHARTS_AGENT_KEY for paper. The OAuth browser connector does not issue paper keys and answers access_denied.

2. Confirm the account and limits

   Ask the client to call query_account and get_agent_context. Check kind: "paper", the expected account number, tier and risk caps. Then call query_balance, query_positions and query_open_orders before submitting an order. Connection success proves identity; it does not prove that a chosen symbol has fresh pricing or enough buying power.

3. Place one simulated order

   Call place_market_order with an explicit paper venue and a unique caller ID for this logical order:

   {
     "venue": "paper",
     "symbol": "BTC.HL",
     "side": "buy",
     "qty": 0.001,
     "clientOrderId": "demo-20260922-001"
   }

   Use a symbol available to your account’s trading group; B3 paper symbols such as WIN.B3 use the same venue: "paper" setting. The platform enforces prop rules, risk caps and buying power before simulated dispatch. Read the returned state: dispatched is not a fill.

4. Recover, cancel or stop

   If the call times out, first call query_order with the same clientOrderId. If you retry placement, send the same ID and arguments. The OMS returns the original intent instead of creating a second order. Changing the payload while reusing the ID returns a conflict.

   Poll query_order until the intent reaches a terminal state, and check query_positions and query_recent_fills for reconciliation. A resting limit order can be canceled with cancel_order and its intent ID. Use flatten_position with venue: "paper" and a new clientOrderId to close an open position.

   To stop future writes immediately, engage the credential’s kill switch in Lab → MCP, or revoke it there when the connection is no longer needed. Only the workspace operator can release a kill switch or change the key’s tier and caps.

The local client exchanges its API key and secret for a bearer automatically, and every request enforces the key’s account, tier, expiry and OMS controls.

Next: MCP server reference · Track an order · Scopes and tiers