@tronchartsxyz/mcp-server

A Model Context Protocol server that exposes Tron Charts' OMS as tools Claude / GPT / any MCP-capable client can call. Trade perps on Hyperliquid + Aster, observe predictions on Polymarket, and run autonomous strategies — without writing a single REST call.

┌──────────────────┐   stdio MCP    ┌────────────────────┐   HTTPS    ┌──────────────┐
│ Claude Desktop / │ ◀───tools────▶ │  tron-charts-mcp   │ ◀──REST──▶ │ Tron Charts  │
│ Claude Code /    │                │  (this package)    │            │ Provider API │
│ Cursor / etc.    │                │                    │            └──────┬───────┘
└──────────────────┘                │  agent key signs   │                   │
                                    │  HL intents locally│                   ▼
                                    └────────────────────┘            ┌──────────────┐
                                                                       │  HL / Aster  │
                                                                       │  /exchange   │
                                                                       └──────────────┘

The agent's private key never leaves this process. The BE relays the (action, signature) pair to the venue; HL verifies the signature against the agent address pre-authorized via approveAgent. Risk envelope caps + kill switch live BE-side as the trust boundary.

Install

npm install -g @tronchartsxyz/mcp-server

# or one-off via npx:
npx -y @tronchartsxyz/mcp-server

Mint credentials

In Tron Charts → Settings → API Clients → "New for Claude Desktop":

1. Pick a tier (readonly / liquidation / fullTrading)
2. Set risk envelope caps (max position notional, daily loss cap)
3. Generate an agent keypair (FE-side; private key shown ONCE)
4. Sign approveAgent with your main wallet (HL relay happens server-side)
5. Copy:
   • TRON_CHARTS_API_KEY=pk_…
   • TRON_CHARTS_API_SECRET=sk_… ← never recoverable
   • TRON_CHARTS_AGENT_KEY=0x… ← 32-byte hex; never recoverable

The agent address is pre-authorized via HL's approveAgent primitive — your main wallet stays cold; the agent key only has trading permission within its scope + expiry.

Configure Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "tron-charts": {
      "command": "tron-charts-mcp",
      "env": {
        "TRON_CHARTS_API_KEY": "pk_...",
        "TRON_CHARTS_API_SECRET": "sk_...",
        "TRON_CHARTS_AGENT_KEY": "0x...",
        "TRON_CHARTS_BASE_URL": "https://api.troncharts.xyz"
      }
    }
  }
}

Restart Claude Desktop. The tron-charts server should appear in the tools menu with a green dot.

Configure Claude Code

claude mcp add tron-charts --command tron-charts-mcp \
  --env TRON_CHARTS_API_KEY=pk_... \
  --env TRON_CHARTS_API_SECRET=sk_... \
  --env TRON_CHARTS_AGENT_KEY=0x...

Configure Cursor

Cursor → Settings → MCP → Add server. Same env vars; command is tron-charts-mcp on PATH.

Tools

Tier-filtered. Your credential's tier (returned at JWT mint) decides which tools are advertised.

Always available (readonly+)

• query_account — { accountId, accountNumber, tier, agentAddress }. Call once at session start.
• query_balance — per-venue equity / balance / margin / unrealized PnL.
• query_positions — open positions with side / qty / entry / mark / liq / leverage / uPnL.
• query_open_orders — working orders with venueOrderId / type / qty / price.
• query_recent_trades — closed round-trip trades with realized PnL + fees (default 50).
• query_recent_fills — raw per-leg fills (default 100).
• get_agent_context — risk envelope notes + error code reference.

Adds at liquidation tier

• cancel_order — cancel by venueOrderId. Signs + dispatches synchronously.

Adds at fullTrading tier

• place_market_order — IOC market, slip-capped at 5% per HL semantics.
• place_limit_order — Gtc / Ioc / Alo (post-only). Subject to risk envelope.
• flatten_position — close one symbol via reduceOnly market. Fast-fails on "already flat".

Example agent prompts

"Show me my BTC position and current liquidation price."

"If BTC is below $80,000 right now, place a limit buy for 0.001 at $79,500 with post-only."

"Cancel my oldest working order and place a new one 100 USD lower."

"What's my worst trade this week, and what should I learn from it?"

The LLM reads tool descriptions to decide which to call. Structured errors (e.g. risk_envelope_position_notional, kill_switch_engaged, already_flat) come back as tool results so the model self-corrects rather than crashing the conversation.

Risk envelope

Every place_* call hits a compose-time gate that enforces:

• kill_switch — operator hard-stop. Engage via Settings → API Clients → Kill Switch when something goes wrong. All place_* return kill_switch_engaged until reset.
• max_position_notional_usd — single-order notional cap. Order rejects with risk_envelope_position_notional if qty × refPrice exceeds it.
• daily_loss_cap_usd — rolling 24h realized-loss limit. Once tripped, place_* returns risk_envelope_daily_loss until the cap rolls forward.

Caps are enforced BE-side because this process runs on the user's machine — client-side enforcement is worthless. Even if the MCP server were tampered with, the BE gate would still cap exposure.

What's not in v1

• Aster + Polymarket signing. v1 places trades on Hyperliquid only. Aster (HMAC) and Polymarket (EIP-712 Order struct) have different signing schemes that land in a follow-up.
• place_stop_order / place_tp_sl_brackets / modify_order. Limit + market + cancel + flatten covers the canonical agent loop. Stop + bracket tools come once the place pipeline shakes out under real use.
• Long-lived streams (positions / quotes pushed in real-time). MCP's tool model is request/response. For high-frequency strategies use the Tron Charts WSS Provider API directly.
• Multi-account. The bearer is account-scoped. One MCP server instance per account; run two if you need two.

Trust model

| What | Where | Why | |---|---|---| | API key + secret | env on user's machine | rotates via re-mint; revocable via Settings | | 24h JWT bearer | in-memory in this process | auto-refreshed; revocable via blocklist | | Agent private key | env on user's machine | never on BE; venue verifies signature | | approveAgent envelope | signed once by main wallet at mint | grants the agent address trading permission within scope + expiry | | Risk envelope | BE-side enforcement | trust boundary; client-side caps are worthless | | Audit trail | BE order_intents.api_client_id | every agent-placed order tagged + queryable |

Source

Built and maintained alongside the Tron Charts platform. Open issues + feature requests on the main repo.

License

MIT.