Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/ton-org/kit --skill ton-xstocksAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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
| Token | Jetton master |
|---|---|
| USDT (TON) | EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs |
Resolve the TON jetton master for an xStock
- By symbol (e.g.
TSLAx): fetch via `curl` (not WebFetch — the xStocks API returns 403 for non-standard user-agents):
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 samedeploymentsshape.
- Call
get_jetton_infowith--jettonAddress <jetton_master>to confirm name / symbol / decimals before swapping.
MCP tools
| Action | Tools |
|---|---|
| Pre-fund USDT | get_jetton_balance (USDT) → get_swap_quote (GRAM (ex. 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).
CLI argument names (exact)
| Tool | Arg | CLI flag |
|---|---|---|
get_jetton_info | jettonAddress | --jettonAddress |
get_jetton_balance | jettonAddress | --jettonAddress |
get_swap_quote | fromToken | --fromToken (use "TON" for native GRAM (ex. 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 |
Pre-fund USDT (auto, when needed)
Before any xStock trade, check the user's USDT balance:
get_jetton_balancefor the USDT master address — use theamountfield 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 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
- 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_transactionwith the quote'stransaction.messages— verify expected balance changes before sending.- Show the user: fromAmount, toAmount, minReceived, expiresAt, emulation results, and note the forward GRAM (ex. TON) on router messages (gas).
- Confirm once, then
send_raw_transactionwith the returnedtransaction.messages. - Poll
get_transaction_statusonnormalizedHashuntilcompletedorfailed.
Do not attempt GRAM (ex. TON) → xStock directly. It will return no quote. Always route through USDT.
Sell workflow ("sell all" or fixed amount)
get_jetton_balancefor the xStock master → use the returnedamountfield (already a human-readable decimal string, e.g."12.5"). UseamountRawonly if a raw integer is needed elsewhere.- Pass
amountdirectly as theamountparameter forget_swap_quote— no manual conversion needed. get_swap_quote:fromToken= xStock master,toToken= USDT master.emulate_transactionwith the quote'stransaction.messages— verify expected balance changes.- Show the user the quote details and emulation results, then confirm.
send_raw_transaction, then pollget_transaction_statusuntilcompletedorfailed.
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.

