ton-org/kit

ton-xstocks

Buy or sell Backed xStocks (tokenized equities, e.g.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/ton-org/kit --skill ton-xstocks

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

xStocks on TON (buy / sell)

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 GRAM (ex. TON) → xStock and xStock → GRAM 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).

Key addresses

TokenJetton master
USDT (TON)EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

Resolve the TON jetton master for an xStock

  1. 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).

  1. In the JSON, find deployments[] where `network` is `"Ton"`. Use that object's `address` as the jetton master for MCP (fromToken / toToken).
  1. Optional: curl -s "https://api.xstocks.fi/api/v2/public/assets" returns all assets with the same deployments shape.
  1. Call get_jetton_info with --jettonAddress <jetton_master> to confirm name / symbol / decimals before swapping.

MCP tools

ActionTools
Pre-fund USDTget_jetton_balance (USDT) → get_swap_quote (GRAM (ex. TON) → USDT) → emulate_transaction → send_raw_transaction
Buy xStockget_swap_quote (USDT → xStock) → emulate_transaction → send_raw_transaction
Sell xStockget_jetton_balance (xStock) → get_swap_quote (xStock → USDT) → emulate_transaction → send_raw_transaction
Verifyget_jetton_info, get_transaction_status, get_jetton_balance

Amounts for get_swap_quote are human-readable strings (respect jetton decimals from get_jetton_info).

CLI argument names (exact)

ToolArgCLI flag
get_jetton_infojettonAddress--jettonAddress
get_jetton_balancejettonAddress--jettonAddress
get_swap_quotefromToken--fromToken (use "TON" for native GRAM (ex. TON), jetton master address for tokens)
get_swap_quotetoToken--toToken
get_swap_quoteamount--amount (human-readable)
get_swap_quoteslippageBps--slippageBps (default 100 = 1%)
emulate_transactionmessages--messages (JSON array from quote's transaction.messages)
send_raw_transactionmessages--messages (same JSON array)
get_transaction_statusnormalizedHash--normalizedHash

Pre-fund USDT (auto, when needed)

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

  1. get_jetton_balance for the USDT master address — use the amount field for comparison.
  2. 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 GRAM (ex. 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.

Buy workflow

  1. Resolve the Ton jetton master for the xStock symbol (API above).
  2. Check USDT balance — run Pre-fund USDT if insufficient.
  3. get_swap_quote: fromToken = USDT master, toToken = xStock master, amount = USDT to spend, slippageBps = 100 (1 %).
  4. emulate_transaction with the quote's transaction.messages — verify expected balance changes before sending.
  5. Show the user: fromAmount, toAmount, minReceived, expiresAt, emulation results, and note the forward GRAM (ex. TON) on router messages (gas).
  6. Confirm once, then send_raw_transaction with the returned transaction.messages.
  7. Poll get_transaction_status on normalizedHash until completed or failed.
Do not attempt GRAM (ex. TON) → xStock directly. It will return no quote. Always route through USDT.

Sell workflow ("sell all" or fixed amount)

  1. 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.
  2. Pass amount directly as the amount parameter for get_swap_quote — no manual conversion needed.
  3. get_swap_quote: fromToken = xStock master, toToken = USDT master.
  4. emulate_transaction with the quote's transaction.messages — verify expected balance changes.
  5. Show the user the quote details and emulation results, then confirm.
  6. send_raw_transaction, then poll get_transaction_status until completed or failed.
Do not attempt xStock → GRAM (ex. TON) directly. Always sell into 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.

Omniston quirks

  • "No quote available" — no route at that size / time. Retry after a short wait, or adjust amount / slippage slightly. Do not switch to GRAM (ex. 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.

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.
来自同一仓库

更多 Skills

全部 Skills