How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/ton-org/kit --skill ton-xstocksBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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.

