Back to Details

ctrader-mcp-servers

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Top-5 critical quirks (inline teaser)

五大关键特性（内联提要）

The following 5 quirks are the most consequential as of the audit date. Full Detect / Workaround / Verify-fixed / Removal-criteria content lives in 
references/known-quirks.md
; the rows below are link-only teasers. See also 
references/self-healing-playbook.md
for the named recovery patterns.
QuirkServerOne-linerLink
Q-R10remote
amend_position
omitting a leg REMOVES it (not preserves it)		Q-R10
Q-R4remoteMARKET REJECTS absolute SL/TP — use 
relativeStopLoss
/
relativeTakeProfit
(single call) or P-REMOTE-MARKET-2STEP (fallback)		Q-R4
Q-R1remote
period
enum is 9 values, NOT 26 (delete granular claims)		Q-R1
Q-L2localSL is absolute price, TP is raw pips (asymmetric 
get_pending_orders
)		Q-L2
Q-K19bothPipettes vs display foot-gun — silent market fillsQ-K19
以下5个特性是截至审计日期影响最重大的。完整的检测/解决方案/验证修复/移除标准内容请查看
references/known-quirks.md
；下方表格仅为带链接的提要。有关指定恢复模式，另请参阅
references/self-healing-playbook.md
。
特性服务器类型一句话描述链接
Q-R10远程调用
amend_position
时省略某一持仓腿会将其移除（而非保留）		Q-R10
Q-R4远程市价单拒绝绝对止损/止盈（SL/TP）——请使用
relativeStopLoss
/
relativeTakeProfit
（单次调用）或P-REMOTE-MARKET-2STEP（备选方案）		Q-R4
Q-R1远程
period
枚举包含9个值，而非26个（删除粒度相关声明）		Q-R1
Q-L2本地止损为绝对价格，止盈为原始点数（
get_pending_orders
存在不对称性）		Q-L2
Q-K19两者点差小数位与显示风险——无提示的市价成交Q-K19

Self-healing principle

自愈原则

Both 
ctrader-remote-mcp
and 
ctrader-local-mcp
ship as-is with documented runtime behaviors last re-verified on 2026-05-14 against 
rest-proxy 1.0.18
(Remote) and local build observed-on 2026-05-14 (Local). Six Remote quirks remain ACTIVE on 1.0.18 (Q-R1, Q-R2, Q-R3, Q-R5, Q-R8, Q-R10). Two quirks had their error-message format refined (Q-R4 and Q-R7 now return plain-string error envelopes with actionable hints instead of JSON envelopes — both DETECT signatures cover both formats). One quirk is likely fixed (Q-R11 — 
get_deals
propagation lag — passed Verify-fixed on session 1 of 5; not yet removed pending 4 more confirmations). This skill describes SEMANTICS, GOTCHAS, and RECOVERY; the MCP JSON-Schema is the source of truth on SHAPE. Never duplicate schema content in this skill. Every claim about runtime behavior in this skill carries a build-stamp — either an 
as-of:
header on a reference file, or an 
Observed-on:
line on a quirk in 
references/known-quirks.md
.
Every quirk in the ledger is self-deprecating: it carries a 
Verify-fixed
probe (a session-local check the agent can run) and a 
Removal criteria
condition (the explicit signal that the server has been fixed and the entry should be deleted). When the server is fixed, delete the matching entry from 
references/known-quirks.md
— that is the entire cleanup cost. Optional follow-up: 
grep
for any stale QUIRK breadcrumbs across the reference files and remove them.
On unexpected server behavior (anything deviating from BOTH the MCP JSON-Schema AND the ledger), do NOT improvise — follow 
references/self-healing-playbook.md
. The playbook names the pre-flight gates (quote sanity, side-direction, SL/TP sidedness, volume-step, schema-fields-only, pipettes-vs-display detection, required-fields), the post-flight verification rules (re-read after every mutation; for Remote 
amend_position
, always re-read to confirm BOTH SL and TP legs survived per Q-R10), the error-classification matrix (Zod / INVALID_REQUEST / 502 uProxy / plain-text Local / available:false / truncated / hasMore), the unknown-quirk decision tree (4 steps from STOP to provisional ledger entry), and the named patterns (P-AMEND-SAFE, P-REMOTE-MARKET-RELATIVE (preferred for MARKET+SL/TP), P-REMOTE-MARKET-2STEP (fallback for absolute-price SL/TP on MARKET), P-REMOTE-MARKET-RANGE, P-LOCAL-OLDEST-FIRST, P-REMOTE-HISTORY-CHUNK).
ctrader-remote-mcp
和
ctrader-local-mcp
均按原样发布，其记录的运行时行为最后验证于2026-05-14，针对的是
rest-proxy 1.0.18
（远程）和2026-05-14观测到的本地构建版本（本地）。截至1.0.18版本，仍有6个远程特性处于活跃状态（Q-R1、Q-R2、Q-R3、Q-R5、Q-R8、Q-R10）。有两个特性的错误消息格式已优化（Q-R4和Q-R7现在返回带有可操作提示的纯字符串错误包，而非JSON包——两者的检测签名均兼容两种格式）。有一个特性可能已修复（Q-R11——
get_deals
传播延迟——在5次验证会话的第1次中通过了修复验证；需等待另外4次确认后才会移除）。本技能描述的是语义、陷阱和恢复方法；MCP JSON-Schema是结构的权威来源。请勿在本技能中重复Schema内容。本技能中所有关于运行时行为的声明均带有构建标记——要么是参考文件中的
as-of:
表头，要么是
references/known-quirks.md
中特性的
Observed-on:
行。
分类账中的每个特性都具备自弃用机制：带有
Verify-fixed
探测（Agent可运行的会话本地检查）和
Removal criteria
条件（服务器已修复且条目应删除的明确信号）。当服务器修复后，从
references/known-quirks.md
中删除对应条目即可完成清理。可选后续操作：在所有参考文件中搜索过时的特性痕迹并移除。
遇到意外的服务器行为（与MCP JSON-Schema和分类账均不符的情况），请勿自行处理——请遵循
references/self-healing-playbook.md
。该手册包含飞行前检查项（报价合理性、方向、SL/TP方向性、交易量步长、仅Schema字段、点差小数位与显示检测、必填字段）、飞行后验证规则（每次变更后重新读取；对于远程
amend_position
，务必重新读取以确认SL和TP持仓腿均按Q-R10要求保留）、错误分类矩阵（Zod / INVALID_REQUEST / 502 uProxy / 纯文本本地响应 / available:false / 截断 / hasMore）、未知特性决策树（从停止操作到临时分类账条目的4个步骤）以及指定模式（P-AMEND-SAFE、P-REMOTE-MARKET-RELATIVE（市价单+SL/TP的首选方案）、P-REMOTE-MARKET-2STEP（市价单绝对价格SL/TP的备选方案）、P-REMOTE-MARKET-RANGE、P-LOCAL-OLDEST-FIRST、P-REMOTE-HISTORY-CHUNK）。

Per-broker overlay extension point

经纪商专属覆盖扩展点

The skill's quirks ledger uses the 
Q-B<n>
prefix as a reserved slot for future per-broker overrides (lotSize divergences, symbol-naming variants, broker-specific SL/TP behaviors). A future 
assets/broker_overrides.example.json
overlay would carry these per-broker values without restructuring this skill. NOT shipped this iteration — added on demand when broker-specific divergences become a blocking class.
本技能的特性分类账使用
Q-B<n>
前缀作为未来经纪商专属覆盖的预留位（如手数差异、命名变体、经纪商专属SL/TP行为）。未来的
assets/broker_overrides.example.json
覆盖文件将承载这些经纪商专属值，无需重构本技能。当前版本未发布——仅当经纪商专属差异成为阻塞类问题时按需添加。

Tool-surface routing: Local HTTP (
ctrader-local-mcp
) vs Remote HTTP (
ctrader-remote-mcp
)

工具面路由：本地HTTP（
ctrader-local-mcp
）vs 远程HTTP（
ctrader-remote-mcp
）

The bound tool surface determines which cTrader MCP server is in front of you. Inspect tool names and response DTO shape to identify the family. Apply the routing rule below at the start of every cTrader-related interaction; cache the result for the session.
Server familyFingerprint to detect itWhat it does bestDefault routing rule
Local HTTP (
ctrader-local-mcp
)
ping
, 
get_accounts_list
, 
list_charts
, 
listChartIndicators
, 
listPlugins
, 
show_notification
, 
get_server_time
; volume in units; ISO 8601 with mandatory 
Z
; symbol identified by string name (
"EURUSD"
). HTTP transport bound to the cTrader Desktop application.		Charts, drawings, indicators, watchlists, alerts, news, cBots, UI notifications, multi-account work.Route here for any UI / visualization / cBot / chart-bound workflow.
Remote HTTP (
ctrader-remote-mcp
)
get_version
, 
get_assets
, integer 
symbolId
-keyed tools (
get_spot_prices(symbolId)
, 
get_trendbars(symbolId)
); 
moneyDigits
field in money responses; volume in cents (1 lot of forex = 10 000 000); prices in pipettes. HTTP transport against the remote REST proxy (
rest-proxy
).		Headless trading, broad symbol scans, trailing stop loss, 
MARKET_RANGE
, granular timeframe history.		Route here when no chart / UI need exists.
Both surfaces boundBoth fingerprints visible.Depends on the action.Pick by capability: drawings / cBots / charts go to Local; trailing SL / 
MARKET_RANGE
/ multi-symbol batch quotes / granular timeframes go to Remote.
绑定的工具面决定了你面对的是哪款cTrader MCP服务器。通过检查工具名称和响应DTO结构来识别服务器类型。在每次cTrader相关交互开始时应用以下路由规则，并在会话中缓存结果。
服务器类型检测特征擅长场景默认路由规则
本地HTTP（
ctrader-local-mcp
）		包含
ping
、
get_accounts_list
、
list_charts
、
listChartIndicators
、
listPlugins
、
show_notification
、
get_server_time
工具；交易量以单位计算；ISO 8601格式且必须带有
Z
后缀；通过字符串名称（如
"EURUSD"
）识别品种。HTTP传输绑定到cTrader桌面应用。		图表、绘图、指标、观察列表、警报、新闻、cBots、UI通知、多账户操作。任何涉及UI/可视化/cBot/图表绑定的工作流均路由至此。
远程HTTP（
ctrader-remote-mcp
）		包含
get_version
、
get_assets
、以整数
symbolId
为键的工具（如
get_spot_prices(symbolId)
、
get_trendbars(symbolId)
）；资金响应中包含
moneyDigits
字段；交易量以分计算（1手外汇=10 000 000分）；价格以点差小数位计算。HTTP传输对接远程REST代理（
rest-proxy
）。		无界面交易、全品种扫描、追踪止损、
MARKET_RANGE
、精细时间周期历史数据。		当不需要图表/UI时，路由至此。
同时绑定两个工具面可见两种特征。取决于具体操作。根据能力选择：绘图/cBots/图表相关操作选本地；追踪止损/
MARKET_RANGE
/多品种批量报价/精细时间周期选远程。

Units conventions across the two servers

两款服务器的单位约定

The two servers encode the same trading concepts in different units and identifier types; passing Local values to Remote (or the reverse) silently produces wrong sizes, wrong prices, or schema rejections.
DimensionLocal HTTP encodingRemote HTTP encodingConversion script
VolumeUnits (integer; for forex typically 1 lot = 100 000 units, but broker-dependent — always read 
get_symbol_details.lotSize
).		Cents (integer; 1 lot of forex = 10 000 000 cents).
scripts/units_encoding.py lots-to-units
/ 
lots-to-cents
PriceDisplay value (e.g., 
1.21345
).		Pipettes (integer; divide by 
10^pipDigits
to display).
scripts/pip_math.py
(handles both directions)
Money (balance, commission, swap, P&L)Display value (e.g., 
12345.67
).		Integer in 
10^moneyDigits
units (
moneyDigits
field on the response; typically 2).
scripts/units_encoding.py display-money
/ 
parse-money
TimestampISO 8601 with mandatory 
Z
suffix (
2026-01-15T14:30:00Z
).		Epoch milliseconds for 
expirationTimestamp
(integer-only as of rest-proxy 1.0.13); either form for history window endpoints.		Passed through unchanged for Local; check field type for Remote.
Symbol identifierString name (
"EURUSD"
, 
"XAUUSD"
).		Integer 
symbolId
(resolve via 
get_symbols
, cache for the session).		N/A (look up by ID)
Stop loss / take profit on 
place_*_order
/ 
amend_order
Pip distance integer (
stopLossPips
, 
takeProfitPips
).		Absolute price (
stopLoss
, 
takeProfit
).
scripts/pip_math.py pips-to-price
/ 
price-to-pips
两款服务器对相同交易概念的单位和标识符类型编码不同；将本地值传入远程（反之亦然）会无声地导致规模错误、价格错误或Schema拒绝。
维度本地HTTP编码远程HTTP编码转换脚本
交易量单位（整数；外汇通常1手=100 000单位，但取决于经纪商——务必读取
get_symbol_details.lotSize
）。		分（整数；1手外汇=10 000 000分）。
scripts/units_encoding.py lots-to-units
/ 
lots-to-cents
价格显示值（如
1.21345
）。		点差小数位（整数；除以
10^pipDigits
转换为显示值）。
scripts/pip_math.py
（支持双向转换）
资金（余额、佣金、隔夜利息、盈亏）显示值（如
12345.67
）。
10^moneyDigits
单位的整数（响应中的
moneyDigits
字段；通常为2）。
scripts/units_encoding.py display-money
/ 
parse-money
时间戳ISO 8601格式且必须带有
Z
后缀（
2026-01-15T14:30:00Z
）。
expirationTimestamp
为 epoch毫秒数（截至rest-proxy 1.0.13版本仅支持整数）；历史窗口端点支持两种格式。		本地直接传递；远程需检查字段类型。
品种标识符字符串名称（
"EURUSD"
、
"XAUUSD"
）。		整数
symbolId
（通过
get_symbols
解析，会话中缓存）。		无（通过ID查询）
place_*_order
/ 
amend_order
中的止损/止盈		点数距离整数（
stopLossPips
、
takeProfitPips
）。		绝对价格（
stopLoss
、
takeProfit
）。
scripts/pip_math.py pips-to-price
/ 
price-to-pips

Stop loss and take profit: pip distance vs absolute price

止损与止盈：点数距离vs绝对价格

Order-placement tools take SL / TP as pip distance from entry; position-amendment tools take SL / TP as absolute price. The convention depends on which TOOL is called, not which server.
ToolServerSL / TP form
place_market_order
, 
place_limit_order
, 
place_stop_order
, 
place_stop_limit_order
LocalPip distance (
stopLossPips
, 
takeProfitPips
).
amend_order
(pending order)		LocalPip distance (
stopLossPips
, 
takeProfitPips
).
amend_position
(open position)		LocalAbsolute price (
stopLoss
, 
takeProfit
).
create_order
RemoteAbsolute price (
stopLoss
, 
takeProfit
). See 
references/remote-http-server.md
for MARKET-order SL/TP rejection (P-REMOTE-MARKET-2STEP).
amend_order
RemoteAbsolute price (
stopLoss
, 
takeProfit
).
amend_position
RemoteAbsolute price (
stopLoss
, 
takeProfit
).
close_position
BothN/A (no SL / TP parameter).
When the user says "SL 30 pips below entry", convert to the form the target tool needs by running 
scripts/pip_math.py
. Input: 
--pip-size <float> --digits <int> --reference-price <float> --pips <int>
. Output: 
{"absolute_price": <float>, "pip_size_used": <float>}
. The script handles both directions.
下单工具接受相对于入场价的点数距离作为SL/TP参数；持仓修改工具接受绝对价格作为SL/TP参数。约定取决于调用的工具，而非服务器类型。
工具服务器类型SL/TP格式
place_market_order
、
place_limit_order
、
place_stop_order
、
place_stop_limit_order
本地点数距离（
stopLossPips
、
takeProfitPips
）。
amend_order
（挂单）		本地点数距离（
stopLossPips
、
takeProfitPips
）。
amend_position
（持仓）		本地绝对价格（
stopLoss
、
takeProfit
）。
create_order
远程绝对价格（
stopLoss
、
takeProfit
）。市价单SL/TP拒绝相关内容请查看
references/remote-http-server.md
（P-REMOTE-MARKET-2STEP）。
amend_order
远程绝对价格（
stopLoss
、
takeProfit
）。
amend_position
远程绝对价格（
stopLoss
、
takeProfit
）。
close_position
两者无（无SL/TP参数）。
当用户说"SL比入场价低30点"时，请运行
scripts/pip_math.py
转换为目标工具所需格式。输入：
--pip-size <float> --digits <int> --reference-price <float> --pips <int>
。输出：
{"absolute_price": <float>, "pip_size_used": <float>}
。该脚本支持双向转换。

Dynamic-leverage margin calculation

动态杠杆保证金计算

Brokers apply dynamic-leverage tiers: leverage falls as the exposure grows past tier upper bounds. Required margin is computed PER TIER and summed. Tier exposure volumes are stated in USD regardless of the traded symbol; the resulting margin in USD is then converted to the account currency.
Example. Account currency USD. Order: 1 000 000 EURUSD long @ 1.21345. Notional in USD = 1 000 000 × 1.21345 = 1 213 450 USD. Tier curve: 1:500 up to 1 000 000 USD, 1:200 from 1 000 000 to 5 000 000 USD, 1:100 above 5 000 000 USD. Margin = (1 000 000 / 500) + (213 450 / 200) = 2 000 + 1 067.25 = 3 067.25 USD.
Invoke 
scripts/tiered_margin.py compute
to compute this for arbitrary tier curves. Input: 
--volume-base-units <int> --quote-rate-usd <float> --tiers '[{"upper":1000000,"leverage":500},{"upper":5000000,"leverage":200},{"upper":null,"leverage":100}]'
. Output: 
{"margin_usd": <float>, "per_tier_breakdown": [...]}
. Convert the USD margin to the account currency with 
scripts/conversion_rate.py compute-chain
.
经纪商采用动态杠杆 tier：当持仓规模超过tier上限时，杠杆会下降。所需保证金按tier分别计算后求和。Tier持仓规模以美元为单位，无论交易品种为何；最终美元保证金再转换为账户货币。
示例。账户货币为美元。订单：1 000 000手EURUSD多单 @ 1.21345。美元名义价值 = 1 000 000 × 1.21345 = 1 213 450美元。Tier曲线：1:500（上限1 000 000美元）、1:200（1 000 000至5 000 000美元）、1:100（超过5 000 000美元）。保证金 = (1 000 000 / 500) + (213 450 / 200) = 2 000 + 1 067.25 = 3 067.25美元。
调用
scripts/tiered_margin.py compute
计算任意tier曲线的保证金。输入：
--volume-base-units <int> --quote-rate-usd <float> --tiers '[{"upper":1000000,"leverage":500},{"upper":5000000,"leverage":200},{"upper":null,"leverage":100}]'
。输出：
{"margin_usd": <float>, "per_tier_breakdown": [...]}
。使用
scripts/conversion_rate.py compute-chain
将美元保证金转换为账户货币。

Currency conversion: quote currency vs account currency

货币转换：报价货币vs账户货币

When a symbol's quote currency differs from the account currency, every money figure returned by the server (commission, swap, realized P&L, pip value, margin) requires conversion through a chain of spot rates. Example chains: P&L on USDJPY for a EUR account requires JPY -> USD -> EUR (using USDJPY and EURUSD); P&L on AUDCAD for an NZD account requires CAD -> USD -> NZD or a direct AUD -> NZD chain. The cTrader backend builds the shortest available chain; replicate that logic locally with 
scripts/conversion_rate.py
.
Invoke 
scripts/conversion_rate.py compute-chain
to derive the rate. Input: 
--from-asset <CCY> --to-asset <CCY> --quotes '{"EURUSD":1.0850,"USDJPY":150.3,...}'
. Output: 
{"rate": <float>, "chain": ["EURUSD","USDJPY",...], "warnings": [...]}
. Fetch the quote map up front via 
get_spot_prices
for Local (one symbol per call) or 
get_spot_prices(symbolId:[...])
for Remote (batched).
当品种的报价货币与账户货币不同时，服务器返回的所有资金数据（佣金、隔夜利息、已实现盈亏、点值、保证金）都需要通过即期汇率链进行转换。示例链：EUR账户交易USDJPY的盈亏需要JPY -> USD -> EUR（使用USDJPY和EURUSD汇率）；NZD账户交易AUDCAD的盈亏需要CAD -> USD -> NZD或直接AUD -> NZD链。cTrader后端会构建最短可用链；请使用
scripts/conversion_rate.py
在本地复现该逻辑。
调用
scripts/conversion_rate.py compute-chain
获取转换汇率。输入：
--from-asset <CCY> --to-asset <CCY> --quotes '{"EURUSD":1.0850,"USDJPY":150.3,...}'
。输出：
{"rate": <float>, "chain": ["EURUSD","USDJPY",...], "warnings": [...]}
。提前通过本地
get_spot_prices
（单次调用一个品种）或远程
get_spot_prices(symbolId:[...])
（批量调用）获取报价映射。

Hedging vs netting accounts

对冲账户vs净额账户

Hedging accounts allow simultaneous long AND short positions on the same symbol (each gets its own 
positionId
). Netting accounts collapse them: opening the opposite side automatically closes (or partially closes) the existing position to the net delta. Before placing the second leg of a hedge, read the existing position and the account's hedging mode (visible in 
get_balance
and account-info responses); if the account is netting, "opening a hedge" is impossible — surface this to the user and propose either a stop-loss adjustment or a full close instead.
对冲账户允许同一品种同时持有多单和空单（各有独立
positionId
）。净额账户会将其合并：开立反向仓位会自动平仓（或部分平仓）现有仓位以实现净delta。在开立对冲仓位前，请读取现有持仓和账户对冲模式（
get_balance
和账户信息响应中可见）；如果是净额账户，"开立对冲仓位"是不可能的——请告知用户并建议调整止损或全部平仓。

Stop-out and margin level

强制平仓与保证金水平

Brokers force-close positions when margin level = (equity / used margin) × 100% falls to or below the stop-out level (commonly 50% or 30%, broker-set). Two policies exist: fair (closes the single position consuming the most margin) and smart (closes the smallest set of positions sufficient to restore margin level above the stop-out). Before sizing additional risk, read current equity and used margin; if 
(equity − required_new_margin) / used_margin_after_open × 100%
drops below 2× the stop-out level, warn the user before proceeding.
当保证金水平 = (权益 / 已用保证金) × 100%降至或低于强制平仓水平（通常为50%或30%，由经纪商设定）时，经纪商会强制平仓。有两种策略：公平策略（平仓占用保证金最多的单个仓位）和智能策略（平仓最少数量的仓位以恢复保证金水平至强制平仓线以上）。在增加风险规模前，请读取当前权益和已用保证金；如果
(权益 − 新增所需保证金) / 开仓后已用保证金 × 100%
降至强制平仓水平的2倍以下，请先警告用户再继续操作。

Swap accrual timing

隔夜利息计息时间

Swap (overnight financing) accrues at broker server time rollover (commonly 23:59:59 server time). Many brokers triple-charge swap on Wednesday (the Wed -> Thu rollover absorbs the weekend value date for T+2 instruments like forex). When projecting swap over a holding period, multiply by 3 for any Wednesday in the window. Read swap and commission values directly from 
get_positions
and 
get_deals
responses (they are server-computed); do not re-derive them from rate tables.
隔夜利息（隔夜融资）在经纪商服务器时间轧账时计息（通常为服务器时间23:59:59）。许多经纪商在周三收取三倍隔夜利息（周三至周四的轧账包含T+2工具如外汇的周末交割日价值）。当预测持仓期间的隔夜利息时，窗口内的每个周三都要乘以3。直接从
get_positions
和
get_deals
响应中读取隔夜利息和佣金（由服务器计算）；请勿从费率表重新推导。

Composable trader workflows

可组合交易者工作流

Seven end-to-end trader workflows are described step-by-step in 
references/trader-workflows.md
. W0 (session bootstrap) auto-runs once at session start; W1–W6 are dispatched by user-intent triggers. When the user request matches any trigger, read 
references/trader-workflows.md
and follow the corresponding recipe — do not improvise from scratch.
  1. W0 — Session bootstrap — auto-runs at session start; identifies server family, probes live build, caches symbol precision baseline from 
    assets/symbol_precision_table.json
    , resolves active account, and sets the idempotency-key prefix. No user trigger needed.
  2. Position sizing by risk % — select this recipe when the user asks "how much to buy / sell", "size for N pips SL", "risk X% of my account on this trade", or any sentence combining a risk fraction with a stop-loss distance.
  3. Pre-trade briefing — select this recipe when the user asks "should I trade X", "give me a snapshot of X before I enter", "what does X look like right now", or combines symbol-details + price + recent history requests into one ask.
  4. Cost-of-trading comparison — select this recipe when the user asks "which is cheaper to trade, A or B", "compare spreads / commissions / swap across symbols", or ranks tradeable instruments by cost.
  5. Place + visualize a trade with risk/reward annotation — select this recipe when the user asks "place the trade and show it on the chart", "draw the R:R on EURUSD", and the Local HTTP server is bound (this workflow requires drawings).
  6. Multi-window historical backfill — select this recipe when the user asks for more bars than a single 
    get_trendbars
    call returns (1000 cap on Local), e.g., "give me 5000 H1 candles of XAUUSD" or "show me the last year of D1".
  7. Safe flatten — select this recipe when the user asks "close everything", "cancel all my orders", "flatten my book", or any request to bulk-close pending orders and open positions on one or more symbols.
references/trader-workflows.md
中详细描述了7个端到端交易者工作流。W0（会话引导）在会话开始时自动运行；W1–W6由用户意图触发。当用户请求匹配任何触发器时，请读取
references/trader-workflows.md
并遵循对应流程——请勿从头自行设计。
  1. W0 — 会话引导 — 会话开始时自动运行；识别服务器类型、探测实时构建版本、从
    assets/symbol_precision_table.json
    缓存品种精度基线、解析活跃账户并设置幂等键前缀。无需用户触发。
  2. 按风险百分比计算仓位规模 — 当用户询问"买/卖多少"、"N点SL对应的仓位规模"、"用账户X%的资金做这笔交易"或任何将风险比例与止损距离结合的问题时，选择此流程。
  3. 交易前简报 — 当用户询问"我应该交易X吗"、"交易X前给我一份快照"、"X现在是什么情况"或同时请求品种详情+价格+近期历史数据时，选择此流程。
  4. 交易成本比较 — 当用户询问"交易A和B哪个更便宜"、"比较品种的点差/佣金/隔夜利息"或按成本对可交易品种排名时，选择此流程。
  5. 下单并可视化带风险/回报标注的交易 — 当用户询问"下单并在图表上显示"、"在EURUSD上绘制风险回报比"且已绑定本地HTTP服务器（此工作流需要绘图功能）时，选择此流程。
  6. 多窗口历史数据回填 — 当用户请求的K线数量超过单次
    get_trendbars
    调用上限（本地为1000条）时，选择此流程，例如"给我5000条XAUUSD的H1蜡烛图"或"显示去年的D1数据"。
  7. 安全平仓 — 当用户询问"平仓所有仓位"、"取消所有订单"、"清空我的持仓"或任何批量平仓挂单和持仓的请求时，选择此流程。

Server-specific reference files

服务器专属参考文件

When the bound tool surface includes Local HTTP tools (
ping
, 
get_accounts_list
, 
list_charts
, 
listChartIndicators
, 
listPlugins
, 
show_notification
, 
get_server_time
), read 
references/local-http-server.md
for the Local capability map, encoding rules, pagination caps, identifier types, active-chart targeting, drawing-object anchor requirements, and the destructive-operations checklist.
When the bound tool surface includes Remote HTTP tools (
get_version
, 
get_assets
, integer 
symbolId
-keyed tools, 
moneyDigits
in responses), read 
references/remote-http-server.md
for the Remote capability map, encoding rules, the 9-value 
period
enum, server-side validations, 
timeInForce
semantics, 
dealStatus
enum, and the cache-discipline rules for 
get_symbols
.
When both surfaces are bound, read both files.
当绑定的工具面包含本地HTTP工具（
ping
、
get_accounts_list
、
list_charts
、
listChartIndicators
、
listPlugins
、
show_notification
、
get_server_time
）时，请阅读
references/local-http-server.md
获取本地能力映射、编码规则、分页上限、标识符类型、活跃图表定位、绘图对象锚点要求和破坏性操作检查表。
当绑定的工具面包含远程HTTP工具（
get_version
、
get_assets
、以整数
symbolId
为键的工具、响应中的
moneyDigits
）时，请阅读
references/remote-http-server.md
获取远程能力映射、编码规则、9值
period
枚举、服务器端验证、
timeInForce
语义、
dealStatus
枚举和
get_symbols
缓存规则。
当同时绑定两个工具面时，请阅读两个文件。

Bundled scripts

捆绑脚本

Non-trivial computation lives in 
scripts/
. Invoke a script whenever the math goes beyond a single multiplication or addition. Every script accepts CLI flags only (non-interactive), prints JSON to stdout, prints diagnostics to stderr, and documents itself via 
--help
.
ScriptPurposeInvocation patternOutput shape
scripts/pip_math.py
Convert between pip distance and absolute price (display values; operates on both servers' encoding once pipettes are decoded).
python scripts/pip_math.py pips-to-price --pip-size 0.0001 --digits 5 --reference-price 1.0850 --pips 30
{"absolute_price": 1.08800, "pip_size_used": 0.0001}
scripts/position_sizing.py
Compute order size from a risk-percent or risk-amount target, accounting for pip value and quote -> account-currency conversion.
python scripts/position_sizing.py from-risk-percent --balance 10000 --risk-pct 1 --sl-pips 30 --pip-value-per-lot 10 --conversion-rate 1.0
{"units": 33333, "cents": 3333333, "risk_currency_amount": 100.0, "warnings": []}
scripts/tiered_margin.py
Reproduce cTrader's dynamic-leverage margin formula across a tier curve.
python scripts/tiered_margin.py compute --volume-base-units 1000000 --quote-rate-usd 1.21345 --tiers '[{"upper":1000000,"leverage":500},{"upper":5000000,"leverage":200},{"upper":null,"leverage":100}]'
{"margin_usd": 3067.25, "per_tier_breakdown": [...]}
scripts/conversion_rate.py
Build the shortest spot-rate chain to convert between two currencies.
python scripts/conversion_rate.py compute-chain --from-asset JPY --to-asset USD --quotes '{"USDJPY":150.3}'
{"rate": 0.006653, "chain": ["USDJPY"], "warnings": []}
scripts/units_encoding.py
Convert between display lots and the wire encoding for each server (units / cents); convert between display money and 
moneyDigits
integers.
python scripts/units_encoding.py lots-to-cents --lots 0.1 --lot-size 100000
{"cents": 1000000}
复杂计算逻辑位于
scripts/
目录下。当计算超出单次乘法或加法时，请调用脚本。每个脚本仅接受CLI参数（非交互式）、向stdout输出JSON、向stderr输出诊断信息并通过
--help
提供文档。
脚本用途调用模式输出格式
scripts/pip_math.py
在点数距离和绝对价格（显示值；点差小数位解码后可用于两款服务器的编码）之间转换。
python scripts/pip_math.py pips-to-price --pip-size 0.0001 --digits 5 --reference-price 1.0850 --pips 30
{"absolute_price": 1.08800, "pip_size_used": 0.0001}
scripts/position_sizing.py
根据风险百分比或风险金额目标计算订单规模，考虑点值和报价货币到账户货币的转换。
python scripts/position_sizing.py from-risk-percent --balance 10000 --risk-pct 1 --sl-pips 30 --pip-value-per-lot 10 --conversion-rate 1.0
{"units": 33333, "cents": 3333333, "risk_currency_amount": 100.0, "warnings": []}
scripts/tiered_margin.py
复现cTrader基于tier曲线的动态杠杆保证金计算公式。
python scripts/tiered_margin.py compute --volume-base-units 1000000 --quote-rate-usd 1.21345 --tiers '[{"upper":1000000,"leverage":500},{"upper":5000000,"leverage":200},{"upper":null,"leverage":100}]'
{"margin_usd": 3067.25, "per_tier_breakdown": [...]}
scripts/conversion_rate.py
构建最短即期汇率链以实现两种货币之间的转换。
python scripts/conversion_rate.py compute-chain --from-asset JPY --to-asset USD --quotes '{"USDJPY":150.3}'
{"rate": 0.006653, "chain": ["USDJPY"], "warnings": []}
scripts/units_encoding.py
在显示手数与各服务器的编码（单位/分）之间转换；在显示资金与
moneyDigits
整数之间转换。
python scripts/units_encoding.py lots-to-cents --lots 0.1 --lot-size 100000
{"cents": 1000000}

Post-order validation loop

下单后验证循环

After any mutating call (
place_*_order
, 
create_order
, 
amend_order
, 
amend_position
, 
close_position
, 
cancel_order
), re-fetch the affected entity (
get_positions
, 
get_pending_orders
, or 
get_position_details
) and verify that volume, side, entry price (for fills), SL, TP, and 
dealStatus
match the user's stated intent. If any value mismatches, identify the mismatch class:
  • Encoding error -> re-run 
    scripts/units_encoding.py
    or 
    scripts/pip_math.py
    and retry with corrected inputs.
  • Broker rejection (
    dealStatus: REJECTED
    / 
    INTERNALLY_REJECTED
    / 
    ERROR
    ) -> surface the rejection reason from the server response to the user and stop.
Do not assume the order is filled just because the call returned without an exception.
完成任何变更调用（
place_*_order
、
create_order
、
amend_order
、
amend_position
、
close_position
、
cancel_order
）后，请重新获取受影响的实体（
get_positions
、
get_pending_orders
或
get_position_details
）并验证交易量、方向、入场价（针对成交单）、SL、TP和
dealStatus
是否与用户意图匹配。如果任何值不匹配，请识别不匹配类型：
  • 编码错误 -> 重新运行
    scripts/units_encoding.py
    或
    scripts/pip_math.py
    并使用修正后的输入重试。
  • 经纪商拒绝（
    dealStatus: REJECTED
    / 
    INTERNALLY_REJECTED
    / 
    ERROR
    ） -> 将服务器响应中的拒绝原因告知用户并停止操作。
请勿仅因调用无异常返回就假设订单已成交。