ton-xstocks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

xStocks on TON (buy / sell)

TON上的xStocks（买卖操作）

Backed xStocks are jettons on TON. Resolve the jetton master from the public xStocks API, then use the same quote → execute flow as

ton-swap

, with routing preferences learned from real Omniston behavior.

Critical: USDT is the only working swap pair.
Omniston consistently returns no quote for TON → xStock and xStock → TON routes.
All xStock buys and sells must go through USDT. If the user lacks sufficient USDT, buy USDT with TON first (see §Pre-fund USDT below).

Backed xStocks是TON上的jetton代币。从公开的xStocks API获取jetton master地址，然后遵循与

ton-swap

相同的报价→执行流程，路由规则参考Omniston的实际行为逻辑。

重要提示：USDT是唯一可用的兑换交易对。
对于TON→xStock和xStock→TON的兑换路径，Omniston始终返回无报价。
所有xStock的买卖操作必须通过USDT进行。如果用户USDT余额不足，请先将TON兑换为USDT（见下文「预充值USDT」章节）。

Key addresses

关键地址

Token	Jetton master
USDT (TON)	`EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs`

代币	Jetton master地址
USDT (TON)	`EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs`

Resolve the TON jetton master for an xStock

为xStock获取对应的TON jetton master地址

By symbol (e.g.
```
TSLAx
```
): fetch via curl
(not WebFetch — the xStocks API returns 403 for non-standard user-agents):
bash
```
curl -s "https://api.xstocks.fi/api/v2/public/assets/{symbol}"
```
(production base:
```
https://api.xstocks.fi/api/v2
```
— see xStocks API).
In the JSON, find
```
deployments[]
```
where network
is
"Ton"
. Use that object's address
as the jetton master for MCP (
```
fromToken
```
/
```
toToken
```
).

Optional:

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

returns all assets with the same

deployments

shape.

Call
```
get_jetton_info
```
with
```
--jettonAddress <jetton_master>
```
to confirm name / symbol / decimals before swapping.

通过代币符号（例如
```
TSLAx
```
）：使用**
```
curl
```
**命令获取（不要用WebFetch——xStocks API会对非标准用户代理返回403错误）：
bash
```
curl -s "https://api.xstocks.fi/api/v2/public/assets/{symbol}"
```
（生产环境基础地址：
```
https://api.xstocks.fi/api/v2
```
——详见xStocks API文档）。
在返回的JSON中，找到**
```
network
```
为
```
"Ton"
```
的
deployments[]
对象。使用该对象的
```
address
```
**作为MCP兑换时的jetton master地址（对应
```
fromToken
```
/
```
toToken
```
参数）。
可选操作：执行
```
curl -s "https://api.xstocks.fi/api/v2/public/assets"
```
可获取所有资产的信息，格式同样包含
```
deployments
```
字段。
在执行兑换前，调用
```
get_jetton_info
```
命令并传入
```
--jettonAddress <jetton_master>
```
，确认代币的名称/符号/小数位数。

MCP tools

MCP工具说明

Action	Tools
Pre-fund USDT	`get_jetton_balance` (USDT) → `get_swap_quote` (TON → USDT) → `emulate_transaction` → `send_raw_transaction`
Buy xStock	`get_swap_quote` (USDT → xStock) → `emulate_transaction` → `send_raw_transaction`
Sell xStock	`get_jetton_balance` (xStock) → `get_swap_quote` (xStock → USDT) → `emulate_transaction` → `send_raw_transaction`
Verify	`get_jetton_info` , `get_transaction_status` , `get_jetton_balance`

Amounts for

get_swap_quote

are human-readable strings (respect jetton decimals from

get_jetton_info

操作	所用工具
预充值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

返回的代币小数位数）。

CLI argument names (exact)

CLI参数名称（精确匹配）

Tool	Arg	CLI flag
`get_jetton_info`	jettonAddress	`--jettonAddress`
`get_jetton_balance`	jettonAddress	`--jettonAddress`
`get_swap_quote`	fromToken	`--fromToken` (use `"TON"` for native TON, jetton master address for tokens)
`get_swap_quote`	toToken	`--toToken`
`get_swap_quote`	amount	`--amount` (human-readable)
`get_swap_quote`	slippageBps	`--slippageBps` (default 100 = 1%)
`emulate_transaction`	messages	`--messages` (JSON array from quote's `transaction.messages` )
`send_raw_transaction`	messages	`--messages` (same JSON array)
`get_transaction_status`	normalizedHash	`--normalizedHash`

工具	参数	CLI标识
`get_jetton_info`	jettonAddress	`--jettonAddress`
`get_jetton_balance`	jettonAddress	`--jettonAddress`
`get_swap_quote`	fromToken	`--fromToken` （原生TON使用 `"TON"` 字符串，代币使用jetton master地址）
`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`

Pre-fund USDT (auto, when needed)

预充值USDT（自动触发，当需要时）

Before any xStock trade, check the user's USDT balance:

```
get_jetton_balance
```
for the USDT master address — use the
```
amount
```
field for comparison.
If
```
amount
```
< required amount for the planned buy: a. Calculate the shortfall (include a small buffer for price movement). b.
```
get_swap_quote
```
with
```
fromToken
```
=
```
"TON"
```
(the literal string, not an address),
```
toToken
```
= USDT master,
```
amount
```
= shortfall. c. Confirm with the user: "You need ~X USDT but only have Y. Swap Z TON → X USDT first?" d. On approval,
```
send_raw_transaction
```
→ poll
```
get_transaction_status
```
until
```
completed
```
. e. Re-check USDT balance before proceeding to the xStock buy.

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

调用
```
get_jetton_balance
```
查询USDT master地址对应的余额——使用返回的
```
amount
```
字段进行比较。
如果
```
amount
```
< 买入所需金额： a. 计算差额（需预留少量缓冲以应对价格波动）。 b. 调用
```
get_swap_quote
```
，参数
```
fromToken
```
=
```
"TON"
```
（字符串字面量，而非地址），
```
toToken
```
= USDT master地址，
```
amount
```
= 差额金额。 c. 向用户确认：「您需要约X USDT，但当前仅持有Y USDT。是否先将Z TON兑换为X USDT？」 d. 获得用户批准后，执行
```
send_raw_transaction
```
→轮询
```
get_transaction_status
```
直到交易状态为
```
completed
```
。 e. 再次检查USDT余额，确认充足后再进行xStock买入操作。

Buy workflow

买入流程

Resolve the Ton jetton master for the xStock symbol (API above).
Check USDT balance — run Pre-fund USDT if insufficient.
```
get_swap_quote
```
:
```
fromToken
```
= USDT master,
```
toToken
```
= xStock master,
```
amount
```
= USDT to spend,
```
slippageBps
```
= 100 (1 %).
```
emulate_transaction
```
with the quote's
```
transaction.messages
```
— verify expected balance changes before sending.
Show the user: fromAmount, toAmount, minReceived, expiresAt, emulation results, and note the forward TON on router messages (gas).

Confirm once, then

send_raw_transaction

with the returned

transaction.messages

Poll

get_transaction_status

normalizedHash

until

completed

failed

Do not attempt TON → xStock directly. It will return no quote. Always route through USDT.

为目标xStock代币符号获取对应的Ton jetton master地址（使用上述API方法）。
检查USDT余额——如果不足，执行预充值USDT流程。
调用
```
get_swap_quote
```
：参数
```
fromToken
```
= USDT master地址，
```
toToken
```
= xStock master地址，
```
amount
```
= 要花费的USDT金额，
```
slippageBps
```
= 100（即1%）。
使用报价返回的
```
transaction.messages
```
执行
```
emulate_transaction
```
——在发送交易前验证预期的余额变化是否正确。
向用户展示：fromAmount（转出金额）、toAmount（转入金额）、minReceived（最低到账金额）、expiresAt（报价过期时间）、模拟交易结果，并提示路由消息中包含的正向TON（作为Gas费用）。
获得用户一次确认后，使用返回的
```
transaction.messages
```
执行
```
send_raw_transaction
```
。

轮询

get_transaction_status

（传入

normalizedHash

）直到交易状态为

completed

或

failed

。

请勿直接尝试TON→xStock的兑换路径。 该路径将返回无报价。必须始终通过USDT中转。

Sell workflow ("sell all" or fixed amount)

卖出流程（「全部卖出」或固定金额卖出）

```
get_jetton_balance
```
for the xStock master → use the returned
```
amount
```
field (already a human-readable decimal string, e.g.
```
"12.5"
```
). Use
```
amountRaw
```
only if a raw integer is needed elsewhere.
Pass
```
amount
```
directly as the
```
amount
```
parameter for
```
get_swap_quote
```
— no manual conversion needed.
```
get_swap_quote
```
:
```
fromToken
```
= xStock master,
```
toToken
```
= USDT master.
```
emulate_transaction
```
with the quote's
```
transaction.messages
```
— verify expected balance changes.
Show the user the quote details and emulation results, then confirm.

send_raw_transaction

, then poll

get_transaction_status

until

completed

failed

Do not attempt xStock → TON directly. Always sell into USDT.

调用
```
get_jetton_balance
```
查询xStock master地址对应的余额→使用返回的
```
amount
```
字段（已为人类可读的十进制字符串，例如
```
"12.5"
```
）。仅当需要原始整数值时，才使用
```
amountRaw
```
字段。
将
```
amount
```
直接作为
```
get_swap_quote
```
的
```
amount
```
参数传入——无需手动转换格式。
调用
```
get_swap_quote
```
：参数
```
fromToken
```
= xStock master地址，
```
toToken
```
= USDT master地址。
使用报价返回的
```
transaction.messages
```
执行
```
emulate_transaction
```
——验证预期的余额变化是否正确。
向用户展示报价详情和模拟交易结果，获得确认后再执行下一步。

执行

send_raw_transaction

，然后轮询

get_transaction_status

直到交易状态为

completed

或

failed

。

请勿直接尝试xStock→TON的兑换路径。 必须始终兑换为USDT。

Post-trade checks

交易后检查

If balance reads 0 immediately after a buy, wait a few seconds and re-query; indexers can lag.
After a sell, confirm USDT balance increased as expected.

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

Omniston quirks

Omniston的特殊情况

"No quote available" — no route at that size / time. Retry after a short wait, or adjust amount / slippage slightly. Do not switch to TON pairing; it won't help.
Occasional WebSocket errors (e.g. quote ack) — retry
```
get_swap_quote
```
.
Quotes expire; if the user waited before confirming, fetch a fresh quote before executing.

「无可用报价」：当前金额或时间点无可用兑换路径。请稍等片刻后重试，或小幅调整金额/滑点。请勿切换为TON配对；这不会解决问题。
偶尔会出现WebSocket错误（例如报价确认失败）——**重新调用
```
get_swap_quote
```
**即可。
报价会过期；如果用户在确认前等待了较长时间，执行交易前请重新获取最新报价。

Relations

关联内容

Execution and confirmation rules: ton-swap
skill.
Wallet funding and status polling: ton-balance
skill.
Issuance / redemption outside DEX: xStocks product docs / dashboard — not covered by MCP swap alone.

执行与确认规则：**
```
ton-swap
```
**技能。
钱包充值与状态轮询：**
```
ton-balance
```
**技能。
DEX之外的发行/赎回操作：请参考xStocks产品文档/控制台——本MCP兑换工具不涵盖该部分内容。