ton-connect/kit/ton-xstocks

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

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

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

CLI argument names (exact)

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.