@tronchartsxyz/mcp-server
v0.2.0
Published
Model Context Protocol server for Tron Charts — trade perps + predictions from Claude / GPT / any MCP client.
Maintainers
Readme
@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 │
└──────────────┘With TRON_CHARTS_AGENT_KEY, Hyperliquid actions can be signed locally;
that private key never leaves the MCP process. Without it, the OMS uses
existing backend-provisioned venue credentials. Aster and Polymarket
require backend signing; the wizard-generated local key does not provision
those venues. Risk envelope caps and the kill switch are enforced by the API.
Paper accounts use the platform's simulated matching engine and no agent key.
Install
npm install -g @tronchartsxyz/mcp-server
# or one-off via npx:
npx -y @tronchartsxyz/mcp-serverLive Hyperliquid credentials
In Tron Charts → Lab → MCP → mint a new key (also available in Settings → API Clients):
- Pick a tier (readonly / liquidation / fullTrading)
- Set risk envelope caps (max position notional, daily loss cap)
- Generate an agent keypair (FE-side; private key shown ONCE)
- Sign
approveAgentwith your main wallet (HL relay happens server-side) - Copy:
TRON_CHARTS_API_KEY=pk_…TRON_CHARTS_API_SECRET=sk_…← never recoverableTRON_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.
Simulated / prop-firm accounts
Select the paper-backed prop or simulated account before opening Lab → MCP. Minting a key for that account needs no wallet approval or agent private key. Copy API key + secret and the generated configuration; paper credentials remain active until revoked. Existing account trading-group, prop and OMS risk rules still apply.
Pass venue: "paper" to place_market_order, place_limit_order,
place_stop_order or flatten_position. Symbols use the platform's normal
format, including B3. The backend rejects paper mode against a live account.
Use cancel_order with the paper working order ID. Paper execution returns
mode: "paper"; a dispatched order is not necessarily filled. Give every
logical order a unique clientOrderId. If a tool call times out, first use
query_order with that ID to recover the current state. Repeating the exact
order with the same ID returns the original intent, even after the 24-hour
HTTP idempotency cache expires. Changing the order while reusing its ID is
rejected.
For example, a simulated market tool call is:
{ "venue": "paper", "symbol": "BTC.HL", "side": "buy", "qty": 0.001, "clientOrderId": "strategy-20260922-001" }Live funded prop accounts are not paper accounts. Their custody/signing
requirements remain separate. To test unpublished changes, build this package
and use node /absolute/path/to/mcp-server/dist/index.js as the stdio command;
npx only receives the new tools once this version is published.
Configure Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or
%APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"tron-charts": {
"command": "npx",
"args": ["-y", "@tronchartsxyz/mcp-server"],
"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 and check that the server connects and exposes its tools.
Configure Claude Code
claude mcp add --transport stdio --scope user \
--env TRON_CHARTS_API_KEY=pk_... \
--env TRON_CHARTS_API_SECRET=sk_... \
--env TRON_CHARTS_AGENT_KEY=0x... \
--env TRON_CHARTS_BASE_URL=https://api.troncharts.xyz \
tron-charts -- npx -y @tronchartsxyz/mcp-serverConfigure Cursor
Use the same JSON above in Cursor's MCP configuration. The platform wizard
sets TRON_CHARTS_BASE_URL to the current application origin, which must proxy
/api to this backend. Use your deployment's API origin if it does not.
Omit TRON_CHARTS_AGENT_KEY for Aster/Polymarket or backend signing.
Hosted endpoint
For a browser-based connector, add https://<your app host>/api/mcp as a
remote Streamable HTTP server and choose OAuth. Discovery advertises a public
client registration endpoint, authorization-code + S256 PKCE, and rotating
refresh tokens. The browser opens Tron Charts, where you sign in and approve
one owned paper account and the requested tier. Full-trading consent requires
positive notional and daily-loss caps. The connector receives a one-hour
account/resource-scoped bearer; it never sees an API key or wallet secret.
Revoking the connection in Lab → MCP immediately disables the credential.
The local stdio flow above still exchanges its API key and secret at
POST /api/auth/api-token. For manual hosted clients, the JWT from that
endpoint can be used as Authorization: Bearer <token>; the API key itself
is not a bearer token. Hosted MCP sessions bind to their initializing bearer,
so refreshed tokens start a new MCP session. Unknown session IDs return 404.
The package's standalone HTTP mode is a separate, single-credential service.
Tools
Tier-filtered. Your credential's tier (returned at JWT mint) decides which tools are advertised.
Always available (readonly+)
query_account— { accountId, accountNumber, kind, tier, agentAddress }. Call once at session start.query_order— current canonical intent state, by intent ID or paper clientOrderId.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.place_stop_order— trigger-based order.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_* returnkill_switch_engageduntil reset.max_position_notional_usd— single-order notional cap. Order rejects withrisk_envelope_position_notionalifqty × refPriceexceeds it.daily_loss_cap_usd— rolling 24h realized-loss limit. Once tripped, place_* returnsrisk_envelope_daily_lossuntil 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
- Local Aster + Polymarket signing. These venues require existing backend credentials. Only the Hyperliquid local signer ships in this package.
- Local signing for orchestration tools.
modify_order,reverse_position,attach_bracketsandcancel_all_ordersrequire backend signing. Querytools/listfor the tier-filtered catalog. - 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.
