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为可用兑换对。
Omniston始终会针对TON→xStock和xStock→TON路由返回无报价。
所有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中，找到
```
deployments[]
```
数组里**
```
network
```
为
```
"Ton"
```
的对象，使用该对象的
```
address
```
**作为MCP兑换时的
```
fromToken
```
/
```
toToken
```
对应的jetton master。
可选操作：调用
```
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余额：

针对USDT master地址调用
```
get_jetton_balance
```
——使用返回的
```
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
```
。

轮询

normalizedHash

对应的

get_transaction_status

，直到状态变为

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.

针对xStock master调用
```
get_jetton_balance
```
→ 使用返回的
```
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兑换相关操作。