ton-xstocks

TON 上的 xStocks（买入 / 卖出）

有资产支持的 xStocks 是 TON 上的 jetton。通过公开的 xStocks API 解析 jetton 主合约，然后使用与 ton-swap 相同的 报价 → 执行 流程，并采用从真实 Omniston 行为中总结出的路由偏好。

重要：USDT 是唯一可用的兑换交易对。
Omniston 始终无法为 TON → xStock 和 xStock → TON 路由返回报价。
所有 xStock 买入和卖出都必须经过 USDT。如果用户的 USDT 不足，请先用 TON 买入 USDT（见下文 §预先充值 USDT）。

关键地址

代币	Jetton 主合约
USDT (TON)	EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

解析 xStock 对应的 TON jetton 主合约

1. 按代号（例如 TSLAx）：使用 curl 获取（不要使用 WebFetch — xStocks API 会对非标准 user-agent 返回 403）：

   curl -s "https://api.xstocks.fi/api/v2/public/assets/{symbol}"
   

   （生产环境基础 URL：https://api.xstocks.fi/api/v2 — 参见 xStocks API）。

2. 在 JSON 中，找到 network 为 "Ton" 的 deployments[] 条目。将该对象的 address 用作 MCP 的 jetton 主合约（fromToken / toToken）。

3. 可选：curl -s "https://api.xstocks.fi/api/v2/public/assets" 会返回所有资产，且具有相同的 deployments 结构。

4. 使用 --jettonAddress <jetton_master> 调用 get_jetton_info，在兑换前确认名称 / 代号 / 小数位数。

MCP 工具

操作	工具
预先充值 USDT	get_jetton_balance（USDT）→ get_swap_quote（TON → USDT）→ emulate_transaction → send_raw_transaction
买入 xStock	get_swap_quote（USDT → xStock）→ emulate_transaction → send_raw_transaction
卖出 xStock	get_jetton_balance（xStock）→ get_swap_quote（xStock → USDT）→ emulate_transaction → send_raw_transaction
验证	get_jetton_info、get_transaction_status、get_jetton_balance

get_swap_quote 的金额必须是人类可读字符串（根据 get_jetton_info 获取的 jetton 小数位数填写）。

CLI 参数名称（精确）

工具	参数	CLI 标志
get_jetton_info	jettonAddress	--jettonAddress
get_jetton_balance	jettonAddress	--jettonAddress
get_swap_quote	fromToken	--fromToken（原生 TON 使用 "TON"，代币使用 jetton 主合约地址）
get_swap_quote	toToken	--toToken
get_swap_quote	amount	--amount（人类可读）
get_swap_quote	slippageBps	--slippageBps（默认值为 100 = 1%）
emulate_transaction	messages	--messages（来自报价中 transaction.messages 的 JSON 数组）
send_raw_transaction	messages	--messages（相同的 JSON 数组）
get_transaction_status	normalizedHash	--normalizedHash

预先充值 USDT（需要时自动执行）

进行任何 xStock 交易前，检查用户的 USDT 余额：

1. 对 USDT 主合约地址调用 get_jetton_balance — 使用 amount 字段进行比较。
2. 如果 amount < 计划买入所需金额： a. 计算不足金额（为价格波动预留少量缓冲）。 b. 调用 get_swap_quote，其中 fromToken = "TON"（字面字符串，不是地址），toToken = USDT 主合约，amount = 不足金额。 c. 向用户确认：“您需要约 X USDT，但目前只有 Y USDT。要先将 Z TON 兑换为 X USDT 吗？” d. 获得批准后，调用 send_raw_transaction → 轮询 get_transaction_status，直到状态为 completed。 e. 继续买入 xStock 前重新检查 USDT 余额。

买入工作流

1. 解析 xStock 代码对应的 Ton jetton 主合约（使用上方 API）。
2. 检查 USDT 余额——如果余额不足，运行 预充值 USDT。
3. get_swap_quote：fromToken = USDT 主合约，toToken = xStock 主合约，amount = 要花费的 USDT 数量，slippageBps = 100（1 %）。
4. 使用报价中的 transaction.messages 调用 emulate_transaction——发送前核实预期的余额变化。
5. 向用户展示：fromAmount、toAmount、minReceived、expiresAt、模拟结果，并说明路由器消息中附带的 TON 用于 gas。
6. 确认一次，然后使用返回的 transaction.messages 调用 send_raw_transaction。
7. 轮询 get_transaction_status 中的 normalizedHash，直到状态为 completed 或 failed。

不要尝试直接将 TON 兑换为 xStock。 这样不会返回报价。始终通过 USDT 路由。

卖出工作流（“全部卖出”或固定数量）

1. 对 xStock 主合约调用 get_jetton_balance → 使用返回的 amount 字段（已是便于阅读的小数形式字符串，例如 "12.5"）。仅在其他地方需要原始整数时才使用 amountRaw。
2. 将 amount 直接作为 get_swap_quote 的 amount 参数传入——无需手动转换。
3. get_swap_quote：fromToken = xStock 主合约，toToken = USDT 主合约。
4. 使用报价中的 transaction.messages 调用 emulate_transaction——核实预期的余额变化。
5. 向用户展示报价详情和模拟结果，然后请求确认。
6. 调用 send_raw_transaction，然后轮询 get_transaction_status，直到状态为 completed 或 failed。

不要尝试直接将 xStock 兑换为 TON。 始终卖出换取 USDT。

交易后检查

• 如果买入后余额立即显示为 0，请等待几秒后重新查询；索引器可能会有延迟。
• 卖出后，确认 USDT 余额已按预期增加。

Omniston 注意事项

• “没有可用报价”——该数量／时间点没有可用路由。稍等片刻后重试，或略微调整数量／滑点。不要改用 TON 交易对；这无济于事。
• 偶尔会出现 WebSocket 错误（例如报价确认错误）——重试 get_swap_quote。
• 报价会过期；如果用户等待一段时间后才确认，请在执行前获取新报价。

相关内容

• 执行和确认规则：ton-swap 技能。
• 钱包充值和状态轮询：ton-balance 技能。
• DEX 之外的发行／赎回：请参阅 xStocks 产品文档／控制面板——仅使用 MCP swap 无法涵盖。